nextjs-starter

KO | EN

gitlite — search

#c #self-hosted #rag #pdf #chatgpt #ai-agent #reactjs #typescript #claude-code #framework

(★ 9)

No description available.

File Explorer

ZIP Download

- - ci.yml
  - pages.yml
- accessibility.md
- architecture.md
- customization.md
- static-vs-server.md
- - mark.svg
- - article-commerce.svg
  - article-static.svg
  - article-tokens.svg
  - destination-alpine.svg
  - destination-coast.svg
  - destination-fiordland.svg
  - og-default.svg
  - product-bottle.svg
  - product-detail.svg
  - product-lamp.svg
  - product-pack-interior.svg
  - product-pack-side.svg
  - product-pack.svg
  - product-pour.svg
- apply-preset.ts
- validate-static-build.ts
- - error.tsx
  - layout.tsx
  - loading.tsx
  - manifest.ts
  - not-found.tsx
  - page.tsx
  - robots.ts
  - sitemap.ts
- - features.ts
  - navigation.ts
  - preset.generated.ts
  - seo.ts
  - site.ts
  - social.ts
  - theme.ts
- - destinations.ts
  - faqs.ts
  - products.ts
  - services.ts
  - testimonials.ts
- - utils.ts
- - app-providers.tsx
  - cart-provider.tsx
  - theme-provider.tsx
- - globals.css
- - commerce.ts
  - content.ts
  - index.ts
  - tourism.ts
- - commerce.spec.ts
  - content-tourism.spec.ts
  - general.spec.ts
- - product-card.test.tsx
- - cart.test.ts
  - content.test.ts
  - money.test.ts
  - search.test.ts
  - seo.test.ts
  - validation.test.ts
- setup.ts
.dockerignore
.env.example
.gitignore
.prettierignore
.prettierrc.json
AGENTS.md
components.json
CONTRIBUTING.md
Dockerfile
eslint.config.mjs
LICENSE
next.config.ts
nextjs-universal-starter-source.zip
package.json
playwright.config.ts
pnpm-lock.yaml
pnpm-workspace.yaml
postcss.config.mjs
README.md
tsconfig.json
vitest.config.ts

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**Build anything. Ship anywhere.**

A production-grade, static-first Next.js starter for marketing sites, corporate websites, SaaS launches, blogs, tourism platforms, product catalogues and headless storefronts. It combines a polished, rebrandable design system with typed content, provider boundaries, serious SEO, a local commerce experience and a static export contract enforced in CI.

The starter is deliberately complete without credentials, a database, authentication or a CMS. Those concerns can be added in server mode when the product earns the complexity.

![Northstar Universal social preview](https://raw.githubusercontent.com/PAUL24/nextjs-starter/main/public/images/og-default.svg)

## What ships

- Static export and standalone server builds from one codebase
- Next.js App Router and React Server Components by default
- Strict TypeScript with typed configuration, content and adapters
- Tailwind CSS 4 semantic tokens, light/dark/system themes and responsive type
- Focused shadcn-style components using Radix primitives
- Reusable hero, feature, pricing, process, FAQ, team, testimonial, CTA, newsletter and comparison sections
- Typed local Markdown blog with frontmatter, reading time and related posts
- Typed destinations, full travel guides, itinerary, accommodation, map and weather seams
- Typed product catalogue, search, filtering, sorting, variants and persistent local cart
- Zod + React Hook Form contact, newsletter and enquiry patterns
- Metadata, canonical URLs, Open Graph, X cards, sitemap, robots and JSON-LD
- Vitest, Testing Library and Playwright coverage
- Static-export regression validation and current GitHub Actions workflows
- Four credible example websites and reversible presets
- Optional standalone production Docker image

## Supported sites

Landing pages, SaaS and startup sites, agencies, corporate and service businesses, portfolios, tourism boards, travel agencies, hotels and resorts, blogs, documentation and content sites, product catalogues, static or headless ecommerce, event and restaurant sites, and multilingual marketing foundations.

## Technology

The initial compatibility baseline is Next.js 16.3.4, React 19.2.8, Tailwind CSS 4.3.3, TypeScript 6.0.3, ESLint 9.39.5, Vitest 5.0.0, Playwright 1.62.1 and Zod 4.5.4. The registry’s newer TypeScript 7 and ESLint 10 releases were evaluated; the stable Next.js lint stack does not yet support that pair, so the newest compatible majors are pinned. See `pnpm-lock.yaml` for every resolved version.

Other focused dependencies: Radix Accordion/Dialog/Dropdown/Slot, Lucide, React Hook Form, `next-themes`, `gray-matter`, `clsx`, `tailwind-merge` and `class-variance-authority`.

## Prerequisites

- Node.js 22 or newer (Node.js 24 recommended)
- pnpm 11; Corepack reads the pinned package-manager version

```bash
corepack enable
pnpm install
pnpm dev
```

Open [http://localhost:3000](http://localhost:3000). The basic demo needs no environment variables.

## Essential commands

```bash
pnpm dev              # development server
pnpm build            # standalone Next.js server build
pnpm build:static     # export out/ and validate critical files
pnpm start            # run the production server build
pnpm lint             # ESLint, zero warnings
pnpm lint:fix
pnpm typecheck
pnpm test
pnpm test:watch
pnpm test:e2e
pnpm format
pnpm format:check
pnpm preset landing   # also business, tourism or commerce
```

## Important routes

| Route                                      | Purpose                     |
| ------------------------------------------ | --------------------------- |
| `/`                                        | Starter showcase            |
| `/examples/landing`                        | SaaS/product launch example |
| `/examples/business`                       | Consultancy example         |
| `/examples/tourism`                        | Destination brand example   |
| `/examples/shop`                           | Editorial commerce example  |
| `/blog` and `/blog/[slug]`                 | Markdown content system     |
| `/destinations` and `/destinations/[slug]` | Static tourism architecture |
| `/products` and `/products/[slug]`         | Searchable local catalogue  |
| `/cart`                                    | Persistent client cart      |
| `/about`, `/contact`                       | Common business pages       |

## Project map

```text
src/
├── app/                 routes, metadata files and examples
├── components/
│   ├── ui/              focused Radix/shadcn-style primitives
│   ├── sections/        composable page sections
│   ├── commerce/        catalogue, product and cart UI
│   ├── tourism/         destination-specific UI
│   ├── content/         article presentation
│   ├── forms/           validated client forms
│   ├── media/           portable image abstraction
│   └── seo/             structured-data boundary
├── config/              identity, navigation, features, SEO and theme
├── content/blog/        local Markdown articles
├── data/                typed example records
├── lib/                 providers, validation, formatting and helpers
├── providers/           narrow theme and cart client contexts
└── types/               domain contracts
scripts/                 preset and static-build validation
tests/                   unit, integration and browser tests
docs/                    architecture and operating guides
```

## Configuration and branding

Start in `src/config/site.ts`. It owns the name, description, public origin, locale, logo text, email, phone, address, business details and social URLs. Edit `navigation.ts`, `features.ts`, `seo.ts` and `theme.ts` for their specific concerns.

The light and dark semantic roles are at the top of `src/styles/globals.css`. Components consume roles such as `primary`, `surface`, `muted`, `border`, `ring`, `success` and `danger`; a rebrand rarely needs component edits. Read [the customization guide](docs/customization.md).

## Presets

```bash
pnpm preset landing
pnpm preset business
pnpm preset tourism
pnpm preset commerce
```

A preset rewrites only `src/config/preset.generated.ts`. It changes the starter identity and high-level feature visibility; reusable components, data and example routes remain intact. The output is readable, reviewable and safe to commit. Reset the file from Git to return to your previous configuration.

## Content and CMS

Place `.md` files in `src/content/blog` with validated frontmatter:

```yaml
---
title: "A useful title"
description: "A unique search description."
publishedAt: "2026-09-04"
updatedAt: "2026-09-05"
author: "Author Name"
coverImage: "/images/cover.svg"
categories: [Architecture]
tags: [Next.js, Performance]
canonical: "/blog/a-useful-title"
draft: false
---
```

`LocalContentProvider` parses the files, validates frontmatter, estimates reading time and excludes drafts. The intentionally small renderer allows headings, paragraphs, lists and emphasis without arbitrary HTML.

For Sanity, Contentful, Strapi, Payload, WordPress or Directus, implement `ContentProvider`/`CmsProvider`, normalize records to `Article`, and select the provider in server-only code. A static deployment can fetch a CMS during the build; previews, private tokens at request time and webhooks normally belong in server mode or your build platform.

## Commerce

`LocalCommerceProvider` serves typed products and categories. The UI includes product cards, catalogue search, filters, sorting, product metadata, variant selection, quantity controls, a drawer, a cart page, localStorage persistence, integer-minor-unit totals and honest empty states.

To add Shopify, Medusa, WooCommerce, Saleor or a custom API:

1. implement `CommerceProvider`;
2. normalize remote money into integer minor units;
3. provide static product slugs at build time, or switch those routes to server rendering;
4. keep presentation components independent of the vendor SDK.

The browser cart is not a payment system. For a static site, implement `CheckoutProvider` with an external, provider-hosted checkout whose catalogue and price are authoritative. For Stripe Checkout or a multi-item cart, use `pnpm build`, create the session in a trusted Route Handler/Server Action, reload authoritative prices and inventory, validate input, and return only the session URL. Never place a Stripe secret in `NEXT_PUBLIC_*`.

## Tourism, maps and weather

`Destination`, `Attraction`, `Accommodation`, `Itinerary`, `Tour` and `TravelArticle` models support complete static guides. Map and weather features are credential-free placeholders with real provider seams. Implement `MapProvider` for Mapbox, Google Maps or OpenStreetMap and load embeds only when necessary. Add live weather behind a typed provider with caching and a visible timestamp; forecasts are advisory content, not a booking guarantee.

## Forms

Contact, newsletter and enquiry examples use Zod, React Hook Form, connected errors and a honeypot. `LocalFormProvider` performs no network request. Replace it with Formspree, Basin, Getform or a custom REST endpoint. Public provider IDs may use `NEXT_PUBLIC_`; secret credentials must stay on a server. Always validate again at the trusted endpoint and add abuse protection there.

## SEO

`createMetadata()` produces consistent page metadata while routes provide unique titles, descriptions, canonical paths and images. `sitemap.ts` discovers static pages, articles, products and destinations. `robots.ts` respects `NEXT_PUBLIC_ALLOW_INDEXING=false` for preview environments. JSON-LD utilities cover Organization, WebSite, BreadcrumbList, Article, Product/Offer, FAQPage and TouristDestination.

Structured data must match visible content. The JSON-LD component safely escapes `<`; it is the only reviewed raw-script boundary in the source.

## Images and fonts

`AppImage` centralizes aspect ratio, responsive `sizes`, priority, lazy loading, object fit and loading background. Static builds set `images.unoptimized` and do not need the Next.js image server. Local SVG illustrations are original, lightweight and safe to replace.

- Static/local: keep optimized files under `public/images` and supply honest dimensions/ratios.
- Next.js server: the same component uses the built-in optimizer.
- Cloudinary/ImageKit: build a transformed URL in a provider and pass it to `AppImage`; allowed hosts are in `next.config.ts`.
- Custom CDN: return a complete public URL and use the `custom` provider mode when the CDN owns optimization.

The default system font stacks avoid a network dependency and layout shift. For branded type, self-host licensed `.woff2` assets and expose `next/font/local` results through the existing CSS variables.

## Internationalization and money

The starter defines a locale type and uses `Intl.NumberFormat`/`Intl.DateTimeFormat`. Money is always stored as integer minor units. Add `next-intl` only when translated routing and message loading are required. Keep logical CSS properties, add localized static parameters, emit `hreflang` metadata and set `dir="rtl"` for RTL locales.

## Analytics and privacy

`AnalyticsProvider` defaults to a no-op and no third-party script loads. Implement a small adapter for GA, GTM, Plausible, Umami or Vercel Analytics, mount it only when configured, and respect consent and regional privacy obligations. Do not make rendering depend on analytics availability.

## Static export

```bash
pnpm build:static
```

This sets `NEXT_PUBLIC_BUILD_MODE=static`, enables `output: "export"`, uses trailing slashes, disables the server image optimizer and emits `out/`. The validator then checks representative example, article, product and destination HTML plus `sitemap.xml` and `robots.txt`.

Compatible targets include GitHub Pages, Cloudflare Pages, Netlify, Azure Static Web Apps, Firebase Hosting, AWS S3 + CloudFront, Hostinger, Nginx, Apache and any CDN/static file server. Configure the publish directory as `out`; use no framework server command.

For GitHub Pages, enable Pages with **GitHub Actions** as its source and manually run `.github/workflows/pages.yml`. It sets `basePath` and `assetPrefix` only during that workflow, so repository hosting does not affect normal deployments.

Common static settings:

- Cloudflare Pages / Netlify: build `pnpm build:static`, directory `out`.
- Azure Static Web Apps: app root `/`, output `out`; no API location.
- AWS S3 + CloudFront: upload `out/`, set `index.html` as the root, configure directory-index behavior and immutable caching for hashed assets.
- Hostinger/Apache: upload the contents of `out/` to the public root; preserve trailing-slash directories.
- Nginx: serve `out` and use `try_files $uri $uri/ $uri/index.html =404`.

## Server deployment

```bash
pnpm build
pnpm start
```

- Vercel: import the repository and use the defaults.
- Node.js: deploy `.next/standalone`, `.next/static` and `public`, then run `node server.js`.
- Docker: `docker build -t northstar .` then `docker run --read-only -p 3000:3000 northstar` (provide a writable temporary mount only if a future integration requires one).

Read [static versus server mode](docs/static-vs-server.md) before adding authentication, request-time database access, Server Actions, ISR or secret checkout logic.

## Environment variables

Copy `.env.example` only when needed:

| Variable                     |   Public   | Purpose                                                    |
| ---------------------------- | :--------: | ---------------------------------------------------------- |
| `NEXT_PUBLIC_BUILD_MODE`     |    Yes     | Set automatically by `build:static`; leave unset otherwise |
| `NEXT_PUBLIC_SITE_URL`       |    Yes     | Canonical production origin                                |
| `NEXT_PUBLIC_ALLOW_INDEXING` |    Yes     | Set `false` on non-production previews                     |
| `NEXT_PUBLIC_ANALYTICS_ID`   |    Yes     | Optional adapter-specific public identifier                |
| `GITHUB_PAGES`               | Build only | Enables repository base path in the optional workflow      |

Server secrets must use unprefixed names and be read only by server-only modules.

## Testing and release

```bash
pnpm lint
pnpm typecheck
pnpm test
pnpm build:static
pnpm build
pnpm exec playwright install chromium
pnpm test:e2e
```

Unit tests cover money, cart state, local search, validation, content and structured data. Integration coverage checks reusable UI. Playwright covers navigation, theme, skip link, commerce persistence, article routes and destination routes on desktop and mobile Chromium. CI runs the full static gate on pushes and pull requests.

## Adding authentication or a database

Switch to server deployment first. Choose a maintained auth solution that supports the installed Next.js/React versions, keep session checks in server-only modules, and protect every trusted operation rather than only hiding UI. Introduce a database behind a domain-specific repository/provider; do not import its client into shared components. Validate environment variables at process start and establish migration, backup and least-privilege practices appropriate to the provider.

## Extending safely

- Keep new dynamic routes statically enumerable or explicitly server-only.
- Prefer Server Components and pass serializable data into small interactive islands.
- Add dependencies only when the platform cannot solve the problem cleanly.
- Review `TODO`, `FIXME`, `any`, `@ts-ignore`, lint disables, logging, raw HTML and every new `"use client"` boundary.
- Test at 320, 375, 430, 768, 1024, 1280 and 1440 CSS pixels.
- Preserve the keyboard, contrast, heading, form, reduced-motion and focus guidance in [the accessibility guide](docs/accessibility.md).

## Documentation

- [Architecture](docs/architecture.md)
- [Customization](docs/customization.md)
- [Static versus server](docs/static-vs-server.md)
- [Accessibility](docs/accessibility.md)
- [Contributing](CONTRIBUTING.md)

## Contributing and license

Read `CONTRIBUTING.md`, keep the static export green and include meaningful tests with behavior changes. Northstar Universal is available under the [MIT License](LICENSE).

nextjs-starter

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

nextjs-starter

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README