Skip to main content
NextStarter
Menu

Getting Started

Scaffold a new project, choose a starting point, and have it running locally in a couple of minutes.

Requirements

  • Node.js 24. The version is pinned in .node-version, which nvm, fnm, asdf, and most other version managers read automatically.
  • npm, since the project ships a package-lock.json. pnpm, bun, and yarn also work.
  • Git.

1. Create a project

npx @bill742/create-nextstarter my-project
cd my-project

The CLI asks three questions:

  1. Starting point: blank or full. See Choosing a starting point below.
  2. Site name, which is written to NEXT_PUBLIC_SITE_NAME in .env.
  3. Package manager: npm (the default), pnpm, bun, or yarn. Enter n to skip installing dependencies.

Pass --blank or --full to skip the first question. The CLI clones the template, removes its git history, applies your starting point, copies .env.example to .env, and installs dependencies. The project has no git history yet, so run git init when you are ready to commit.

Choosing a starting point

blankDefault
An empty home page inside the app shell: header, footer, light and dark theme, privacy notice, 404 page, tests, and CI. Start here if you already know what your site looks like. The home page is src/app/page.tsx.
full
The NextStarter landing page, the /ui-components catalogue, and these docs, all kept as example content to adapt. Start here if you would rather edit a working page than begin from nothing.

Both modes remove the content that belongs to NextStarter’s own site: the Pro sales pages, the changelog behind /whats-new, and this site’s metadata. The rules for that live in .nextstarter/. If you clone the repository by hand instead, you get the unmodified site. Run node .nextstarter/apply.mjs blank (or full) to do the same cleanup yourself. It deletes itself afterwards, so it only runs once.

2. Run it locally

npm run dev

Open http://localhost:3000. The dev server uses Turbopack and reloads as you edit. With no keys in .env everything renders. Analytics stays off until you add a PostHog token.

3. Run the checks

These are the same checks CI runs. Run them before you open a pull request:

npm run lint        # ESLint
npm run typecheck   # next typegen, then tsc --noEmit
npm run build       # production build
npm run test        # Playwright + Axe in Chromium, Firefox, and WebKit

The first test run may ask you to install the browsers with npx playwright install. See Testing & CI for the details.

Scripts

npm run dev
Start the development server with Turbopack.
npm run build
Build for production.
npm run start
Serve the production build on port 3000.
npm run lint
Run ESLint.
npm run typecheck
Generate Next.js route types, then type-check the project.
npm run test
Run the Playwright end-to-end and accessibility tests.
npm run lighthouse / lighthouse:desktop
Run Lighthouse against a production build, using the mobile or desktop preset. It starts and stops the server itself.
npm run doctor
Run React Doctor for lint, accessibility, and bundle-size findings.

Next steps