TailNext

A production-ready template for building marketing sites and blogs with Next.js 16, React 19 and Tailwind CSS 4.

What's inside

Framework	Next.js 16 (App Router, Turbopack) with React 19
Styling	Tailwind CSS 4, CSS-first @theme configuration
Language	TypeScript 6, strict mode
Content	MDX through content-collections, frontmatter validated with Zod
Highlighting	Shiki at build time, light and dark themes
Testing	Every Storybook story runs as a browser test in Vitest, with axe accessibility checks
Tooling	ESLint 9 flat config, Prettier, husky, lint-staged, commitlint

Dark mode, SEO metadata, Open Graph images, JSON-LD, a native sitemap and security headers are wired up rather than left as exercises.

Getting started

git clone https://github.com/arthelokyo/tailnext.git
cd tailnext
npm ci
npm run dev

Then open http://localhost:3000.

Node 24 is the target. .nvmrc pins it, and engines sets the floor at 20.9.

Commands

Command	Description
npm run dev	Development server on localhost:3000
npm run build	Production build to .next/
npm start	Serve the production build
npm test	Run every story as a browser test, including accessibility
npm run test:watch	Same, in watch mode
npm run storybook	Storybook on localhost:6006
npm run build-storybook	Static Storybook build
npm run lint / lint:fix	ESLint
npm run typecheck	TypeScript, no emit
npm run prettier / prettier:check	Formatting

Project structure

app/                      App Router routes, sitemap, robots, OG images
  (blog)/blog/            Blog index and /blog/[slug]
  (legal)/                Privacy and terms
  (pages)/                About, contact, faqs, pricing, services
src/
  assets/styles/base.css  Tailwind entry point and @theme tokens
  components/
    atoms/                Logo, theme toggle, menu toggle, providers
    common/               Building blocks shared by widgets
    widgets/              Page sections composed from data
  content/
    blog/                 Posts as .mdx
    legal/                Privacy and terms as .mdx
  shared/data/            Page copy, typed
  stories/                Storybook stories, which double as the test suite
  utils/                  Metadata helpers
content-collections.ts    Content schema and MDX pipeline
src/config.ts             Site name, origin, title, description

Configuration

Site-wide settings live in src/config.ts. The canonical origin can be overridden per environment with NEXT_PUBLIC_SITE_ORIGIN, which is useful for preview deployments and forks; see .env.example.

Design tokens are defined in src/assets/styles/base.css under @theme. Tailwind 4 has no tailwind.config.js.

Writing content

Add an .mdx file to src/content/blog:

---
title: 'Post title'
description: 'Shown in search results and social cards'
publishDate: 'Nov 02 2022'
image: 'https://images.unsplash.com/photo-...'
tags: [markdown, blog]
---

Your content. Code blocks are highlighted by Shiki.

Frontmatter is validated at build time. A missing title or an unparseable publishDate fails the build with a specific message instead of rendering something wrong.

Set draft: true to keep a post out of the site.

Testing

There is no separate test directory. Stories are the tests:

npm test

Each story renders in headless Chromium and is checked with axe. An accessibility violation fails the run, so regressions surface before review.

Deploy

The build is a standard Next.js application and runs anywhere Next.js does.

Set NEXT_PUBLIC_SITE_ORIGIN to the deployed domain so canonical URLs, the sitemap and social cards point at the right place.

Contributing

See CONTRIBUTING.md. Security reports go through SECURITY.md, which also documents the known advisories in the MDX toolchain.

License

MIT — see LICENSE.md.