Strapi Project Scaffolding#

Overview#

Strapi v5 projects are generated via create-strapi (a thin wrapper) and create-strapi-app (the implementation). The recommended invocation is:

npx create-strapi@latest
# or
npm create strapi@latest

create-strapi 1 simply re-exports create-strapi-app, which contains all scaffolding logic 2. Source lives at packages/cli/create-strapi/ and packages/cli/create-strapi-app/ in the monorepo 3 4.

Scaffolding Architecture#

create-strapi-app produces a project from one of four bundled templates 5:

The scaffolding pipeline: template copy → package.json generation (using mergePackageJson() via lodash.mergeWith, which replaces arrays rather than merging by index to prevent stale lock-file entries 6) → dependency install → optional git init.

Key CLI flags 7:

• --ts / --js — language (TypeScript is default)
• --use-npm / --use-yarn / --use-pnpm — package manager
• --non-interactive — skip all prompts, use defaults (requires <directory> argument)
• --skip-db — SQLite with no prompts
• --template <name-or-url> — custom template
• --no-run — create without starting the server

pnpm note: Strapi requires dependency hoisting. For pnpm, add hoist=true to .npmrc or use --use-pnpm flag so the scaffold writes the correct pnpm-workspace.yaml / package.json#pnpm.onlyBuiltDependencies 8. Strapi Cloud does not support pnpm. 7

Known Bugs in Freshly Scaffolded v5 Projects (5.49–5.50.x)#

Several regressions introduced between 5.49.0 and 5.50.1 break the admin panel in freshly generated projects. All are rooted in Vite bundle configuration.

1. ReferenceError: Prism is not defined — Blank Admin Panel#

Versions affected: 5.49.0–5.50.1 (5.48.1 is unaffected) 9

Symptom: Admin panel renders a completely blank page; browser console shows ReferenceError: Prism is not defined. Reproduces on a fresh npx create-strapi-app@5.50.1 project with no modifications. 10

Root cause: @strapi/content-manager's Blocks Code.mjs references Prism.languages and Prism.tokenize as globals, but Vite does not expose the imported prismjs module as a global after bundling. 9

Fix: PR #26978 (merged 2026-07-14) — adds prismjs/components/*.js to Vite's optimizeDeps.include globally and moves the prismjs preload import to the top of the content-manager admin entry. 11

Workaround (pre-fix): Add as the first import in src/admin/app.[t|j]sx:

import Prism from 'prismjs';
if (typeof window !== 'undefined') { window.Prism = Prism; }

Or downgrade all @strapi/* packages to 5.48.1. 10

2. CodeMirror Duplicate Instance — JSON Fields / Nested Components Crash#

Versions affected: 5.50.0–5.50.1 12

Symptom: Opening any content entry with a JSON field or nested component throws:

Unrecognized extension value in extension set ([object Object]). This sometimes happens because multiple instances of @codemirror/state are loaded, breaking instanceof checks.

The error sticks for all subsequent entries in the same session. Affects JSON fields (#26951) and nested/sub-components (#26985) equally. 12 13

Root cause: Vite bundles multiple copies of @codemirror/state and related packages at runtime, breaking instanceof checks that CodeMirror relies on internally. 14

Fix: PR #27007 — adds @codemirror/state, @codemirror/view, @codemirror/language, @codemirror/lang-json, @codemirror/commands, @codemirror/lint, and @uiw/react-codemirror to resolve.dedupe, resolve.alias, and optimizeDeps.include in both Vite and Webpack configs. Scheduled for release 2026-07-15. 14

Workaround (pre-fix): Create src/admin/vite.config.js:

const path = require("path");
const { mergeConfig } = require("vite");
module.exports = (config) => mergeConfig(config, {
  resolve: {
    dedupe: ["@codemirror/state", "@codemirror/view", "@codemirror/language",
             "@codemirror/commands", "@uiw/react-codemirror", "@strapi/design-system"],
    alias: {
      "@codemirror/state": path.resolve(__dirname, "../../node_modules/@codemirror/state"),
      "@codemirror/view": path.resolve(__dirname, "../../node_modules/@codemirror/view"),
    },
  },
});

12

3. package-lock.json Out of Sync (zod@3 vs zod@4) — npm ci Fails#

Versions affected: 5.50.1 15

Symptom: A fresh scaffold's package-lock.json pins zod@3.25.67 but the resolved dependency tree requires zod@4.4.3. npm ci fails immediately on the untouched project:

npm error Invalid: lock file's zod@3.25.67 does not satisfy zod@4.4.3

Breaks CI/CD workflows that use npm ci for reproducible installs. 15

Workaround: Run npm install --package-lock-only in the project root to regenerate a synced lockfile, after which npm ci will succeed. 15

4. Redux Duplicate Context in pnpm Monorepos — Blank Admin Panel#

Versions affected: 5.48.1 in pnpm monorepos containing packages that depend on @reduxjs/toolkit@^2 16

Symptom: Admin panel loads blank with "Duplicate middleware references found when creating the store".

Root cause: getModulePath() used a bare require.resolve() scoped to @strapi/strapi's location, picking up the hoisted RTK 2.x instead of the RTK 1.9.7 pinned by @strapi/admin. 16

Fix: PR #26756 — scopes resolution to @strapi/admin's package directory using resolveFrom. See also Monorepo Module Resolution for the full context. 16

5. Homepage Crash — RangeError: Start Date is invalid#

Versions affected: 5.50.1 17

Symptom: Admin homepage crashes with RangeError: Start Date is invalid when "Last Published" / "Last Edited" widgets render. The /content-manager/homepage/recent-documents API serializes valid Postgres updatedAt/publishedAt timestamps as empty objects {} instead of ISO strings, causing date-fns's intervalToDuration() to throw. 17

Version Compatibility Quick Reference#

✅ = working, ❌ = broken, — = not confirmed

Key Source Files#