create-next-saas-base

Scaffold a production-ready Next.js SaaS starter — Auth.js credentials auth with 2FA, Stripe billing, static RBAC, and a metered quota engine.

npx create-next-saas-base my-app
# or
npm create next-saas-base my-app

Options
  --skip-install   Do not run the package install step
  --skip-git       Do not initialise a git repository

The CLI copies the template, names the project after its directory, generates NEXTAUTH_SECRET, SECRET_KEY, JWT_SECRET_KEY_FOR_STRIPE_TOKEN and CRON_SECRET into a fresh .env.local, initialises git, and installs dependencies. MONGODB_URI and STRIPE_SECRET_KEY are left blank — fill those in, then npm run seed.

Maintaining this package

The two-copies problem

template/ is a generated mirror of the repository root. Never edit it by hand — edit the repo, then:

npm run sync

prepublishOnly runs the sync and a tarball check automatically, so a publish cannot ship a stale or unsafe copy. template/ is gitignored; it exists only between a sync and a publish.

Publishing

npm version patch      # or minor / major
npm publish            # runs sync + check-tarball first

Three things npm does that will catch you out

A bin path written as "./bin/index.js" gets rewritten — or dropped. npm normalises package.json on publish and only warns:

npm warn publish "bin[create-next-saas-base]" script name was cleaned
npm warn publish "bin[create-next-saas-base]" script name bin/index.js was invalid and removed

The second form, on newer npm, means the published package has no bin at all — npx create-next-saas-base silently does nothing. Write bin paths without the leading ./. scripts/check-tarball.js fails the publish if one creeps back in.

.gitignore and .npmrc are silently dropped from published tarballs. Not a warning — the files are simply absent. So the sync ships them as gitignore and npmrc, and bin/index.js restores the dot when it copies. If you add another dotfile that npm strips, add it to DOTFILE_RENAMES in both files. Verify with:

npm pack --dry-run

.env files are published quite happily. They are not on npm's excluded list, so an .env.local sitting in the repo would ship to the public registry along with whatever live keys it holds. scripts/sync-template.js excludes them and aborts if one slips through; scripts/check-tarball.js re-checks the actual tarball before publish. Keep both — a published secret is a rotated secret, because a tarball cannot be unpublished after 72 hours.

Files

| Path | Purpose | | --- | --- | | bin/index.js | The CLI. No dependencies, by design. | | scripts/sync-template.js | Mirrors the repo into template/, applying exclusions and dotfile renames. | | scripts/check-tarball.js | Pre-publish gate: asks npm what it is about to ship and refuses on secrets or missing files. | | template/ | Generated. Gitignored. Do not edit. |