feat: add defineConfig function to help type config (#18302)

Co-authored-by: Zach Bloomquist <github@chary.us>

cli/lib/cypress.js

@@ -68,6 +68,23 @@ const cypressModuleApi = {
       return cli.parseRunCommand(args)
     },
   },
+
+  /**
+   * Provides automatic code completion for configuration in many popular code editors.
+   * While it's not strictly necessary for Cypress to parse your configuration, we
+   * recommend wrapping your config object with `defineConfig()`
+   * @example
+   * module.exports = defineConfig({
+   *   viewportWith: 400
+   * })
+   *
+   * @see ../types/cypress-npm-api.d.ts
+   * @param {Cypress.ConfigOptions} config
+   * @returns {Cypress.ConfigOptions} the configuration passed in parameter
+   */
+  defineConfig (config) {
+    return config
+  },
 }
 
 module.exports = cypressModuleApi

cli/types/cypress-npm-api.d.ts

@@ -377,6 +377,21 @@ declare module 'cypress' {
      * Cypress does
      */
     cli: CypressCommandLine.CypressCliParser
+
+    /**
+     * Provides automatic code completion for configuration in many popular code editors.
+     * While it's not strictly necessary for Cypress to parse your configuration, we
+     * recommend wrapping your config object with `defineConfig()`
+     * @example
+     * module.exports = defineConfig({
+     *   viewportWith: 400
+     * })
+     *
+     * @see ../types/cypress-npm-api.d.ts
+     * @param {Cypress.ConfigOptions} config
+     * @returns {Cypress.ConfigOptions} the configuration passed in parameter
+     */
+    defineConfig(config: Cypress.ConfigOptions): Cypress.ConfigOptions
   }
 
   // export Cypress NPM module interface

packages/server/test/support/fixtures/projects/config-with-custom-file-js/cypress.config.custom.js

@@ -1,7 +1,9 @@
-module.exports = {
+const { defineConfig } = require('cypress')
+
+module.exports = defineConfig({
   pageLoadTimeout: 10000,
   e2e: {
     defaultCommandTimeout: 500,
     videoCompression: 20,
   },
-}
+})