laimand-nextjs-saas-kit — Next.js 后台模板

SHA-256: b98490ff10ed63ddedaac7bf8684172975f7ce1135662c9657783a597fb0f917

2026-10-03T02:51:56.797Z

# Laimand Next.js SaaS Kit

A reusable, frontend-only Next.js starter for building accessible B2B SaaS dashboards. It combines a configurable application shell, isolated feature modules, deterministic demo data, static-export support, and a tested project initializer.

## Key capabilities

- Responsive desktop sidebar and accessible mobile navigation drawer
- Centralized product, workspace, user, feature, and deployment configuration
- Reusable UI, chart, data-table, layout, and dashboard primitives
- Server-first App Router pages with focused client boundaries
- Deterministic local demo actions and CSV/JSON exports
- Formatting, linting, strict TypeScript, unit, accessibility, responsive, and browser checks
- Portable initialization through interactive prompts or a JSON file
- Optional static export and GitHub Pages workflow

## Technology stack

- Next.js 16.2 and React 19
- TypeScript in strict mode
- Tailwind CSS 4 and centralized CSS custom properties
- Recharts and Lucide React
- pnpm 11 through Corepack on Node.js 24
- Biome, ESLint, Vitest, React Testing Library, Playwright, and Axe

## Included example routes

| Route | Example module |
| --- | --- |
| `/` | Overview |
| `/analytics` | Analytics |
| `/customers` | Customers |
| `/subscriptions` | Optional Subscriptions example |
| `/settings` | Settings |

The routes share one application shell. Disabling the Subscriptions module removes its navigation entry but deliberately leaves the route and source files available as an implementation example.

## Reusable architecture overview

`src/config` owns canonical identity, route metadata, navigation, feature flags, shell composition, and deployment settings. Thin files in `src/app` publish route metadata and render public feature entry points from `src/features`. Shared presentation primitives live in `src/components`, while cross-feature fictional records live in `src/data/demo`.

See [Architecture](docs/kit/architecture.md) and [Feature modules](docs/kit/feature-modules.md) for the ownership rules.

## Quick start

Use the Node.js version in `.nvmrc` and the pnpm version declared in `package.json`:

~~~bash
corepack enable
pnpm install --frozen-lockfile
pnpm dev
~~~

Open [http://localhost:3000](http://localhost:3000), then run `pnpm kit:check` and `pnpm check` before treating the workspace as ready. More detail is available in [Quick start](docs/kit/quick-start.md).

## Create a project from the kit

When this repository is enabled as a GitHub Template Repository:

1. Select **Use this template** on GitHub and create a new repository.
2. Clone the generated repository.
3. Rename the containing directory manually if its local name should differ.
4. Enable Corepack and install the locked dependencies.
5. Inspect `kit.config.example.json`.
6. Preview and apply initialization.
7. Validate the initialized project and replace demo-only content.

`pnpm kit:init` configures the current project. It does not rename the containing directory, initialize Git, create or configure a remote, or add authentication, a backend, a database, billing, or persistence.

## Interactive initialization

~~~bash
pnpm kit:init
~~~

Press Enter to keep a displayed value. The initializer validates every resolved field before changing its two owned files. See [Initialization](docs/kit/initialization.md).

## JSON-based initialization

Copy `kit.config.example.json` to the ignored local file `kit.config.json`, edit it, then run:

~~~bash
pnpm kit:init -- --config ./kit.config.json
~~~

Omitted fields keep their current values; unknown or invalid fields fail validation.

## Dry-run initialization

Preview a JSON configuration without writing files:

~~~bash
pnpm kit:init -- --config ./kit.config.json --dry-run
~~~

For an interactive preview, use `pnpm kit:init -- --dry-run`.

## Configuration validation

~~~bash
pnpm kit:check
~~~

This verifies initializer markers and synchronization between `package.json` and `src/config/project-config.ts`. It does not replace the full project checks.

## Project configuration fields

| Area | Fields |
| --- | --- |
| Package and product | `packageName`, `applicationName`, `applicationShortName`, `brandMark`, `applicationDescription` |
| Workspace | `workspaceName`, `workspaceMark`, `organizationName`, `workspaceSlug`, `supportEmail` |
| Demo user | `userName`, `userInitials`, `userRole` |
| Exports | `exportPrefix` |
| Features | `subscriptionsModule`, `preloaderEnabled`, `demoModeEnabled` |
| Deployment | `githubPagesEnabled`, `githubPagesBasePath` |

Validation rules, constraints, and examples are documented in [Configuration](docs/kit/configuration.md).

## Optional Subscriptions example

Set `subscriptionsModule` to `false` to hide Subscriptions from desktop and mobile navigation. This is configuration-level discovery control, not source deletion or route authorization: `/subscriptions` and `src/features/subscriptions` remain in the project. Remove or secure them explicitly if a client project requires different behavior.

## Development commands

~~~bash
pnpm dev
pnpm build
pnpm start
pnpm format
pnpm format:check
pnpm lint
pnpm lint:fix
pnpm typecheck
pnpm fix
~~~

## Testing commands

~~~bash
pnpm test
pnpm test:watch
pnpm test:e2e
pnpm test:e2e:ui
pnpm check
pnpm check:full
~~~

`pnpm check` runs formatting validation, linting, strict type checking, the Vitest suite, and a production build. `pnpm check:full` adds Playwright coverage in Chromium, Firefox, and WebKit.

## GitHub Pages and static export behavior

Normal `pnpm build` uses standard Next.js output. Setting `GITHUB_PAGES=true`, or enabling Pages in project configuration, switches to a static export in `out/`. `NEXT_PUBLIC_BASE_PATH` overrides the configured project-site base path at build time.

The included `.github/workflows/deploy-pages.yml` builds and deploys on pushes to `main` after GitHub Pages is configured for the generated repository. Static hosting cannot provide server-only features. See [Deployment](docs/kit/deployment.md).

## Portable workflow for another computer

Install the declared Node.js version, enable Corepack, clone or create the repository from the template, and run `pnpm install --frozen-lockfile`. Transfer only intentional source and local environment values; do not copy `node_modules`, `.next`, `out`, coverage, or browser reports. Continue with [Portable workflow](docs/kit/portable-workflow.md).

## Repository structure

~~~text
.
├── .github/workflows/     # CI and optional GitHub Pages deployment
├── docs/kit/              # Starter-kit documentation
├── e2e/                   # Playwright browser tests
├── scripts/kit/           # Portable initializer and validation tooling
├── src/app/               # App Router layouts and thin route entry points
├── src/components/        # Shared charts, tables, layout, UI, and dashboard primitives
├── src/config/            # Canonical project and runtime configuration
├── src/data/demo/         # Shared deterministic fictional data
├── src/features/          # Feature-owned components, data, types, and tests
├── kit.config.example.json
└── package.json
~~~

## Demo-only limitations

This kit is a frontend starter, not a production SaaS or billing system. It includes no authentication, authorization, backend, database, payment processing, production multi-tenancy, or persistence. Demo actions and exports are deterministic and local; they do not mutate a server or represent real customer operations.

Replace fictional data, demo feedback, export assumptions, and client-visible copy before delivery. Add backend services only when the project requirements call for them.

## Documentation index

Start with the [kit documentation index](docs/kit/README.md). It links to quick start, initialization, configuration, architecture, feature modules, deployment, portability, and the client-project checklist.