chore: make the @packages/scaffold-config an independent bundle without needed ts-node to register entrypoint. Both ESM and CJS distributions are built and types are used as source to be compatible with older styles of commonjs bundling. Types are not shipped with the package. (#32614)

AtofStryker · web-flow · commit 7062573933bb · 2025-10-01T15:52:38.000-04:00
diff --git a/guides/esm-migration.md b/guides/esm-migration.md
@@ -10,6 +10,10 @@
 - Unit tests in package are written in TypeScript
 - Does not include scripts or system test migrations
 
+#### Notes
+
+When migrating some of these projects away from the `ts-node` entry [see `@packages/scaffold-config` example](https://github.com/cypress-io/cypress/blob/v15.2.0/packages/scaffold-config/index.js), it is somewhat difficult to make separate browser/node entries as the v8-snapshot [tsconfig.json](https://github.com/cypress-io/cypress/blob/v15.2.0/tooling/v8-snapshot/tsconfig.json) is using an older style of module resolution where the `exports` key inside a package's `package.json` is not well supported. Because of this, we need to find ways to bundle code that is needed internally in the browser vs in node without them being a part of the same bundle. This is a temporary work around until we are able to get every package being able to build as an ES Module, which as that point we can re assess how the Cypress binary is being built as well as v8-snapshots, and will allow us to reconfigure this packages to export content in a more proper fashion.
+
 #### Status
 
 ##### NPM Packages
@@ -57,7 +61,7 @@
 - [ ] packages/rewriter **PARTIAL** - entry point is JS
 - [x] packages/root ✅ **COMPLETED**
 - [x] packages/runner ✅ **COMPLETED**
-- [ ] packages/scaffold-config **PARTIAL** - entry point is JS
+- [x] packages/scaffold-config ✅ **COMPLETED**
 - [ ] packages/server **PARTIAL** - many source/test files in JS. highest priority
 - [ ] packages/socket **PARTIAL** - entry point is JS. Tests are JS
 - [x] packages/stderr-filtering ✅ **COMPLETED**
diff --git a/packages/data-context/src/actions/WizardActions.ts b/packages/data-context/src/actions/WizardActions.ts
@@ -1,5 +1,5 @@
 import type { NexusGenObjects } from '../gen/nxs.gen'
-import { detectFramework, commandsFileBody, supportFileComponent, supportFileE2E, getBundler, CT_FRAMEWORKS, resolveComponentFrameworkDefinition, detectThirdPartyCTFrameworks } from '@packages/scaffold-config'
+import { detectFramework, commandsFileBody, supportFileComponent, supportFileE2E, getBundler, CT_FRAMEWORKS, resolveComponentFrameworkDefinition, detectThirdPartyCTFrameworks, componentIndexHtmlGenerator } from '@packages/scaffold-config'
 import assert from 'assert'
 import path from 'path'
 import Debug from 'debug'
@@ -9,7 +9,6 @@ const debug = Debug('cypress:data-context:wizard-actions')
 
 import type { DataContext } from '..'
 import { addTestingTypeToCypressConfig, AddTestingTypeToCypressConfigOptions } from '@packages/config'
-import componentIndexHtmlGenerator from '@packages/scaffold-config/src/component-index-template'
 
 export class WizardActions {
   constructor (private ctx: DataContext) {}
diff --git a/packages/frontend-shared/cypress/support/mock-graphql/stubgql-Wizard.ts b/packages/frontend-shared/cypress/support/mock-graphql/stubgql-Wizard.ts
@@ -1,7 +1,7 @@
 import type { Wizard, WizardBundler } from '../generated/test-graphql-types.gen'
-import * as wizardDeps from '@packages/scaffold-config/src/dependencies'
 import type { MaybeResolver } from './clientTestUtils'
 import { testNodeId } from './clientTestUtils'
+import { WIZARD_DEPENDENCY_REACT, WIZARD_DEPENDENCY_REACT_DOM, WIZARD_DEPENDENCY_TYPESCRIPT } from '@packages/scaffold-config/browser/dependencies'
 
 const testBundlerVite = {
   type: 'vite',
@@ -34,28 +34,28 @@ const testFrameworks = [
 
 export const stubWizard: MaybeResolver<Wizard> = {
   __typename: 'Wizard',
-  installDependenciesCommand: `npm install -D ${wizardDeps.WIZARD_DEPENDENCY_REACT.package} ${wizardDeps.WIZARD_DEPENDENCY_REACT_DOM.package} ${wizardDeps.WIZARD_DEPENDENCY_TYPESCRIPT.package}`,
+  installDependenciesCommand: `npm install -D ${WIZARD_DEPENDENCY_REACT.package} ${WIZARD_DEPENDENCY_REACT_DOM.package} ${WIZARD_DEPENDENCY_TYPESCRIPT.package}`,
   packagesToInstall: [
     {
       __typename: 'WizardNpmPackage',
       id: 'react',
       satisfied: true,
       detectedVersion: '18.3.1',
-      ...wizardDeps.WIZARD_DEPENDENCY_REACT,
+      ...WIZARD_DEPENDENCY_REACT,
     },
     {
       __typename: 'WizardNpmPackage',
       id: 'react-dom',
       satisfied: true,
       detectedVersion: '18.3.1',
-      ...wizardDeps.WIZARD_DEPENDENCY_REACT_DOM,
+      ...WIZARD_DEPENDENCY_REACT_DOM,
     },
     {
       __typename: 'WizardNpmPackage',
       id: 'typescript',
       satisfied: false,
       detectedVersion: '3.9.4',
-      ...wizardDeps.WIZARD_DEPENDENCY_TYPESCRIPT,
+      ...WIZARD_DEPENDENCY_TYPESCRIPT,
     },
   ],
   allBundlers,
diff --git a/packages/launchpad/src/setup/InstallDependencies.cy.tsx b/packages/launchpad/src/setup/InstallDependencies.cy.tsx
@@ -2,7 +2,7 @@
 import { defaultMessages } from '@cy/i18n'
 import InstallDependencies from './InstallDependencies.vue'
 import { InstallDependenciesFragmentDoc } from '../generated/graphql-test'
-import * as wizardDeps from '@packages/scaffold-config/src/dependencies'
+import { WIZARD_DEPENDENCY_REACT, WIZARD_DEPENDENCY_REACT_DOM, WIZARD_DEPENDENCY_TYPESCRIPT } from '@packages/scaffold-config/browser/dependencies'
 
 describe('<InstallDependencies />', () => {
   beforeEach(function () {
@@ -73,21 +73,21 @@ describe('<InstallDependencies />', () => {
             id: 'react',
             satisfied: true,
             detectedVersion: '18.3.1',
-            ...wizardDeps.WIZARD_DEPENDENCY_REACT,
+            ...WIZARD_DEPENDENCY_REACT,
           },
           {
             __typename: 'WizardNpmPackage',
             id: 'react-dom',
             satisfied: true,
             detectedVersion: '18.3.1',
-            ...wizardDeps.WIZARD_DEPENDENCY_REACT_DOM,
+            ...WIZARD_DEPENDENCY_REACT_DOM,
           },
           {
             __typename: 'WizardNpmPackage',
             id: 'typescript',
             satisfied: true,
             detectedVersion: '2.0.1',
-            ...wizardDeps.WIZARD_DEPENDENCY_TYPESCRIPT,
+            ...WIZARD_DEPENDENCY_TYPESCRIPT,
           },
         ]
 
diff --git a/packages/launchpad/src/setup/ManualInstall.cy.tsx b/packages/launchpad/src/setup/ManualInstall.cy.tsx
@@ -1,10 +1,10 @@
 import sinon from 'sinon'
 import { ManualInstallFragmentDoc } from '../generated/graphql-test'
 import ManualInstall from './ManualInstall.vue'
-import * as deps from '@packages/scaffold-config/src/dependencies'
 // tslint:disable-next-line: no-implicit-dependencies - need to handle this
 import { defaultMessages } from '@cy/i18n'
 import { Clipboard_CopyToClipboardDocument } from '../generated/graphql'
+import { WIZARD_DEPENDENCY_REACT, WIZARD_DEPENDENCY_TYPESCRIPT } from '@packages/scaffold-config/browser/dependencies'
 
 describe('<ManualInstall />', () => {
   it('playground', () => {
@@ -18,8 +18,8 @@ describe('<ManualInstall />', () => {
   })
 
   it('lists packages and can copy install command to clipboard', { viewportWidth: 800, viewportHeight: 600 }, () => {
-    const framework = deps.WIZARD_DEPENDENCY_REACT
-    const language = deps.WIZARD_DEPENDENCY_TYPESCRIPT
+    const framework = WIZARD_DEPENDENCY_REACT
+    const language = WIZARD_DEPENDENCY_TYPESCRIPT
 
     const stubCopy = sinon.stub()
 
diff --git a/packages/scaffold-config/.eslintignore b/packages/scaffold-config/.eslintignore
@@ -1 +1,4 @@
 **/tsconfig.json
+cjs/
+esm/
+browser/
diff --git a/packages/scaffold-config/.gitignore b/packages/scaffold-config/.gitignore
@@ -1 +1,3 @@
-src/**/*.js
+cjs/
+esm/
+browser/
diff --git a/packages/scaffold-config/README.md b/packages/scaffold-config/README.md
@@ -9,23 +9,30 @@ We will also attempt to scaffold a configuration file for projects using React a
 ### Supported Frameworks and Libraries
 
 | Name             | Version| Dev Server | Version | Library            | Component Adaptor          | Example Project                                                     |
-| ---------------- | -------| ---------- | ------- | ------------------ | -------------------------- | ------------------------------------------------------------------- |
-| React            | -      | Vite       | 4, 5    | React 18, 19       | `@cypress/react@latest`    | [Link](../../system-tests/projects/react-vite-ts-configured)        |
-| React            | -      | Webpack    | 4, 5    | React 18, 19       | `@cypress/vue@latest`      | [Link](../../system-tests/projects/react18)                         |
-| Vue              | -      | Vite       | 4, 5, 6 | Vue 3              | `@cypress/react@latest`    | [Link](../../system-tests/projects/vue3-vite-ts-configured)         |
-| Vue              | -      | Webpack    | 4, 5    | Vue 3              | `@cypress/vue@latest`      | [Link](../../system-tests/projects/vue3-webpack-ts-configured)      |
-| Angular          | -      | Webpack    | 5       | Angular 17, 18, 19 | `@cypress/angular@latest`  | [Link](../../system-tests/projects/angular-cli-configured)          |
-| Svelte           | -      | Vite       | 4, 5, 6 | Svelte 5           | `@cypress/svelte@latest`   | [Link](../../system-tests/projects/svelte-vite-configured)          |
-| Svelte           | -      | Webpack    | 4, 5    | Svelte 5           | `@cypress/svelte@latest`   | [Link](../../system-tests/projects/svelte-webpack-configured)       |
-| Next.js          | 14, 15 | Webpack    | 4, 5    | React 18, 19       | `@cypress/react@latest`    | [Link](../../system-tests/projects/nextjs-configured)               |
+| ---------------- | -------| ---------- | ---------- | ------------------ | -------------------------- | ------------------------------------------------------------------- |
+| React            | -      | Vite       | 5, 6, 7    | React 18, 19       | `@cypress/react@latest`    | [Link](../../system-tests/projects/react-vite-ts-configured)        |
+| React            | -      | Webpack    | 5          | React 18, 19       | `@cypress/vue@latest`      | [Link](../../system-tests/projects/react18)                         |
+| Vue              | -      | Vite       | 5, 6, 7    | Vue 3              | `@cypress/react@latest`    | [Link](../../system-tests/projects/vue3-vite-ts-configured)         |
+| Vue              | -      | Webpack    | 5          | Vue 3              | `@cypress/vue@latest`      | [Link](../../system-tests/projects/vue3-webpack-ts-configured)      |
+| Angular          | -      | Webpack    | 5          | Angular 17, 18, 19 | `@cypress/angular@latest`  | [Link](../../system-tests/projects/angular-cli-configured)          |
+| Svelte           | -      | Vite       | 5, 6, 7    | Svelte 5           | `@cypress/svelte@latest`   | [Link](../../system-tests/projects/svelte-vite-configured)          |
+| Svelte           | -      | Webpack    | 5          | Svelte 5           | `@cypress/svelte@latest`   | [Link](../../system-tests/projects/svelte-webpack-configured)       |
+| Next.js          | 14, 15 | Webpack    | 5    | React 18, 19       | `@cypress/react@latest`    | [Link](../../system-tests/projects/nextjs-configured)               |
 
 ### Adding More Projects
 
 The process for adding a new library/framework/bundler is as follows:
 
 1. Add your framework in [`src/frameworks.ts`](./src/frameworks.ts).
 2. Any new dependencies are declared in [`src/constants.ts`](./src/constants.ts). Don't forget to add a description.
-3. Ensure your project has the correct library and bundler detected with a test in [`test/unit/detect.spec.ts`](./test/unit/detect.spec.ts).
+3. Ensure your project has the correct library and bundler detected with a test in [`test/unit/detect.spec.ts`](./test/detect.spec.ts).
 3. Add a new project with the correct `cypress.config.js` and `package.json` to [system-tests/projects](../../system-tests/projects). It should be `<name>-configured`, which is a working example with some specs. Ensure it will run on CI by adding it to [`component_testing_spec.ts`](../../system-tests/test/component_testing_spec.ts).
 4. Add another project called `<name>-unconfigured`, which represents the project prior to having Cypress added. This will be used in step 5.
 5. Add a test to [`scaffold-component-testing.cy.ts`](../launchpad/cypress/e2e/scaffold-component-testing.cy.ts) to ensure your project has the correct `cypress.config.js` generated. Use an existing test as a template.
+
+### Internal testing
+
+`@packages/scaffold-config/browser/dependencies` is NOT used in the production binary and therefore doesn't need to be included when the package bundles.
+
+We also build an ESM version of `@packages/scaffold-config` but it isn't currently in use as this packages is only used in server-side CommonJS currently.
+
diff --git a/packages/scaffold-config/index.js b/packages/scaffold-config/index.js
diff --git a/packages/scaffold-config/package.json b/packages/scaffold-config/package.json
@@ -2,12 +2,15 @@
   "name": "@packages/scaffold-config",
   "version": "0.0.0-development",
   "description": "Logic related to scaffolding new projects using launchpad",
-  "main": "index.js",
-  "browser": "src/index.ts",
+  "main": "cjs/index.js",
   "scripts": {
-    "build-prod": "tsc || echo 'built, with errors'",
-    "check-ts": "tsc --noEmit && yarn -s tslint",
-    "clean": "rimraf --glob './src/*.js' './src/**/*.js' './src/**/**/*.js' './test/**/*.js' || echo 'cleaned'",
+    "build": "yarn build:cjs && yarn build:esm && yarn build:browser",
+    "build-prod": "yarn build",
+    "build:browser": "rimraf browser && tsc -p tsconfig.browser.json",
+    "build:cjs": "rimraf cjs && tsc -p tsconfig.cjs.json",
+    "build:esm": "rimraf esm && tsc -p tsconfig.esm.json",
+    "check-ts": "tsc -p tsconfig.cjs.json --noEmit && yarn -s tslint -p tsconfig.cjs.json",
+    "clean": "rimraf esm cjs browser",
     "clean-deps": "rimraf node_modules",
     "lint": "eslint --ext .js,.jsx,.ts,.tsx,.json, .",
     "test": "vitest run",
@@ -28,11 +31,14 @@
   "devDependencies": {
     "@packages/ts": "0.0.0-development",
     "@packages/types": "0.0.0-development",
+    "rimraf": "^6.0.1",
     "vitest": "^3.2.4"
   },
   "files": [
-    "src"
+    "cjs/*",
+    "esm/*"
   ],
   "types": "src/index.ts",
+  "module": "esm/index.js",
   "nx": {}
 }
diff --git a/packages/scaffold-config/src/component-index-template.ts b/packages/scaffold-config/src/component-index-template.ts
@@ -1,6 +1,6 @@
 import dedent from 'dedent'
 
-const componentIndexHtmlGenerator = (headModifier: string = '') => {
+export const componentIndexHtmlGenerator = (headModifier: string = '') => {
   return () => {
     const template = dedent`
     <!DOCTYPE html>
@@ -23,5 +23,3 @@ const componentIndexHtmlGenerator = (headModifier: string = '') => {
     return template.replace(/\n {4}\n/g, '\n')
   }
 }
-
-export default componentIndexHtmlGenerator
diff --git a/packages/scaffold-config/src/ct-detect-third-party.ts b/packages/scaffold-config/src/ct-detect-third-party.ts
@@ -99,7 +99,7 @@ export async function detectThirdPartyCTFrameworks (
 
     // Start at the project root and check each directory above it until we see
     // an indication that the current directory is the root of the repository.
-    await findUp(async (directory: string) => {
+    await findUp(async (directory: string): Promise<findUp.Match> => {
       fullPathGlobs = [
         path.join(directory, CT_FRAMEWORK_GLOBAL_GLOB),
         path.join(directory, CT_FRAMEWORK_NAMESPACED_GLOB),
diff --git a/packages/scaffold-config/src/frameworks.ts b/packages/scaffold-config/src/frameworks.ts
@@ -1,6 +1,6 @@
 import fs from 'fs-extra'
 import * as dependencies from './dependencies'
-import componentIndexHtmlGenerator from './component-index-template'
+import { componentIndexHtmlGenerator } from './component-index-template'
 import debugLib from 'debug'
 import semver from 'semver'
 import { isThirdPartyDefinition } from './ct-detect-third-party'
diff --git a/packages/scaffold-config/test/component-index-template.spec.ts b/packages/scaffold-config/test/component-index-template.spec.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest'
 import dedent from 'dedent'
-import componentIndexHtmlGenerator from '../src/component-index-template'
+import { componentIndexHtmlGenerator } from '../src/component-index-template'
 import { CT_FRAMEWORKS } from '../src/frameworks'
 
 describe('componentIndexHtmlGenerator', () => {
diff --git a/packages/scaffold-config/tsconfig.base.json b/packages/scaffold-config/tsconfig.base.json
@@ -1,18 +1,20 @@
 {
-  "extends": "../ts/tsconfig.json",
-  "include": ["src"],
+  "include": [
+    "src"
+  ],
   "exclude": [
     "test",
     "script"
   ],
-  "files": [
-    "./../ts/index.d.ts"
-  ],
   "compilerOptions": {
-    "lib": ["esnext"],
+    "lib": [
+      "esnext"
+    ],
     "allowJs": false,
     "noImplicitAny": true,
     "noUncheckedIndexedAccess": true,
-    "types": []
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true
   }
 }
diff --git a/packages/scaffold-config/tsconfig.browser.json b/packages/scaffold-config/tsconfig.browser.json
@@ -0,0 +1,17 @@
+{
+  "extends": "./tsconfig.base.json",
+  "include": [
+    "src/dependencies.ts"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./browser",
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "node",
+    "declaration": true,
+    "types": [
+      "cypress"
+    ]
+  }
+}
diff --git a/packages/scaffold-config/tsconfig.cjs.json b/packages/scaffold-config/tsconfig.cjs.json
@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./cjs",
+    "target": "ES2022",
+    "module": "CommonJS",
+    "moduleResolution": "node"
+  }
+}
diff --git a/packages/scaffold-config/tsconfig.esm.json b/packages/scaffold-config/tsconfig.esm.json
@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./esm",
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "node",
+    "noEmit": true
+  }
+}

-Original file line number
+Diff line change
@@ @@ -1 +1,4 @@ @@
 **/tsconfig.json
 +cjs/
 +esm/
 +browser/