Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

nextjs-app-engineering

/nextjs-app-engineering

Prowadzi budowę i wdrażanie aplikacji Next.js App Router w React, TypeScript, Tailwind CSS i Vitest, także przy przenoszeniu projektu wizualnego na kod.

Licencja
Apache-2.0
Ostatnia zmiana repozytorium
02.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
3
Przestarzałość

Brak sygnałów. Repozytorium zmienione 02.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Prowadzi budowę i wdrażanie aplikacji Next.js App Router w React, TypeScript, Tailwind CSS i Vitest, także przy przenoszeniu projektu wizualnego na kod.

Oryginalny opis (EN)

Engineering skill: Next.js full-stack app — how to build and ship a web app with Next.js (App Router) on React, TypeScript, Tailwind CSS, Vitest. Use when writing, reviewing, testing or releasing code in this stack, and when turning a Celestial design or experience skill into code.

Jak działa

  1. Stack
  2. Commands
  3. Structure
  4. Naming
  5. From design and experience skills
  6. Conventions
  7. Do
  8. Don't
  9. Quality gates
  10. Workflow
Sekcje z nagłówków SKILL.md, w oryginale · 169 linii, 2 102 słów
Podgląd SKILL.md
---
name: nextjs-app-engineering
description: "Engineering skill: Next.js full-stack app — how to build and ship a web app with Next.js (App Router) on React, TypeScript, Tailwind CSS, Vitest. Use when writing, reviewing, testing or releasing code in this stack, and when turning a Celestial design or experience skill into code."
type: engineering
stack: web-app
core: "1.0"
checked: 2026-10-26
---

# Next.js full-stack app

A full-stack TypeScript web app on the App Router, rendering on the server by default and shipping client JavaScript only where a screen needs interaction.

For products that need both public pages and signed-in screens in one codebase: marketplaces, SaaS apps, content plus account areas. Pages render as React Server Components, mutations run as server actions, and the app deploys to a Node or edge host with a preview deploy per pull request. Design-skill tokens become a Tailwind theme backed by CSS variables.

## Stack
- **Language:** TypeScript ^5.6 — One type system across server components, server actions and client components.
- **Framework:** Next.js (App Router) on React ^16 · React ^19 — Server rendering, streaming, routing and server actions in one framework.
- **Styling:** Tailwind CSS ^4 — Theme generated from design tokens; works in server and client components alike.
- **State:** Server components + URL search params; client state local to leaf components — Most state lives on the server or in the URL, so it survives refresh and sharing.
- **Data:** Typed data layer (Drizzle ORM on PostgreSQL) called only from server code Drizzle 0.x · PostgreSQL 16+ — Queries stay on the server; the schema doubles as the type source.
- **Build:** Next.js compiler (Turbopack) bundled with Next.js — Fast dev rebuilds and per-route production bundles with no extra config.
- **Hosting:** Node or edge runtime host with preview deploys Node 22 LTS+ — Server actions and streaming need a server; every pull request gets a link.
- **Package manager:** pnpm ^10 — Fast, strict installs with a lockfile CI can trust.
- **Testing:** Vitest ^3 — Fast unit tests for data functions, validators and client components.
- **Testing:** Testing Library ^16 — Component tests query by role and label.
- **Testing:** Playwright ^1.50 — Journey tests against a production build, including server actions and streaming.

## Commands
- dev: `pnpm dev`
- e2e: `pnpm build && pnpm test:e2e`
- lint: `pnpm lint && pnpm typecheck`
- test: `pnpm test`
- build: `pnpm build`
- install: `pnpm install`

## Structure
- `src/app/` — Routes: page.tsx, layout.tsx, loading.tsx, error.tsx and not-found.tsx per segment
- `src/app/(marketing)/ and src/app/(app)/` — Route groups that split public pages from signed-in screens with their own layouts
- `src/components/` — Design-skill components; server components by default, client ones marked at the top
- `src/features/<feature>/` — actions.ts (server actions), queries.ts (server reads), schema.ts (input validation)
- `src/server/` — Database client, auth helpers and anything that must never reach the browser (imports server-only)
- `src/styles/tokens.css` — CSS variables written from the design skill
- `tests/e2e/` — One Playwright spec per experience-skill journey

## Naming
- Files: kebab-case.ts; components PascalCase.tsx; route files use the framework names (page.tsx, layout.tsx)
- Tests: *.test.ts(x) beside the file; tests/e2e/<journey-id>.spec.ts
- Branches: type/short-description, e.g. feat/order-history
- Components: PascalCase, named after the design-skill component; client components end in .client.tsx when a server twin exists

## From design and experience skills
When a Celestial design skill is in use, write its tokens as Tailwind theme in `src/styles/tokens.css`, and build its components in `src/components` with the same names and variants. Components read tokens only — no raw colours, sizes or font names.

When a Celestial experience skill is in use, give each journey one end-to-end test (happy path plus its error and empty states) and name analytics events `object_action` from its measures.

## Conventions
### Code
- Prefer small, pure functions and explicit types at module boundaries. _(Easier to test, review and change.)_

### Components
- Components read design tokens; no raw hex values, pixel sizes or font names in component code. _(One token change restyles the product.)_
- Components are server components unless they need state, effects or browser APIs; put 'use client' on the smallest leaf that does. _(Every client boundary pulls its imports into the browser bundle.)_

### Data
- Analytics events are object_action in snake_case and come from the experience skill’s measures. _(Names stay consistent across teams and tools.)_
- Read data in server components through src/features/*/queries.ts; after a mutation, revalidate the exact path or tag it changed. _(One place to see what is cached and why a screen is stale.)_

### Errors
- Every async action has loading, empty, error and success states, matching the experience skill. _(Unhandled states are where users get stuck.)_
- Every route segment that fetches has loading.tsx and error.tsx; missing records call notFound(). _(Streaming shows progress, and failures stay inside the segment instead of blanking the page.)_

### Security
- Secrets never live in the repository; read them from the environment or a secret store. _(A leaked key outlives the commit that removed it.)_
- Validate every input on the server, even when the client already did. _(Clients can be bypassed.)_
- Web pages ship a Content-Security-Policy, HSTS, X-Frame-Options and nosniff. _(Cheap protection against the most common attacks.)_
- Every server action parses its input with a schema and checks the session before touching data. _(Server actions are public HTTP endpoints, whatever the UI shows.)_
- Modules under src/server/ import 'server-only'; only NEXT_PUBLIC_ variables may be read in client code, and none of them hold secrets. _(The build fails instead of leaking a database client or key to the browser.)_

### Performance
- Images go through next/image with explicit sizes; fonts through next/font; third-party scripts load after interaction. _(Protects LCP and CLS without hand-tuning each page.)_

### Accessibility
- Use native elements first; add ARIA only when no native element fits. _(Native controls bring keyboard and screen-reader support for free.)_
- Each page exports metadata with a unique title, and every page has exactly one h1. _(The route announcer reads the title, so screen-reader users hear where they landed.)_

## Do
- Pass server data to client components as plain serialisable props
- Keep filters, sort order and pagination in search params so views can be shared
- Use useActionState or form status for pending and error states on forms

## Don't
- Fetch your own route handlers from server components; call the query function directly
- Mark a layout or page 'use client' to fix one interactive widget
- Rely on default caching behaviour without stating the cache or revalidate choice in code

## Quality gates
| Gate | Tool | Threshold | When |
|---|---|---|---|
| Lint and types | The stack’s linter and type checker | 0 errors | Every pull request |
| Unit and component tests | The stack’s test runner | All pass; every design-skill component state covered | Every pull request |
| Journey tests | End-to-end runner | One test per experience-skill journey: happy path + error state | Every pull request |
| Accessibility | Automated audit (axe on web, platform audit on mobile) | WCAG 2.2 AA · no new violations | Every pull request |
| Performance budget | next build route report + Lighthouse CI | LCP ≤ 2.5s · INP ≤ 200ms · CLS ≤ 0.1 · ≤ 170KB first-load JS per route | Every pull request |
| Dependency and secret scan | Dependency audit + secret scanner | No high or critical findings; no secrets | Every pull request and nightly |
| Preview deploy | Hosting preview environment | A working preview link on the pull request | Every pull request |
| Server boundary | server-only imports + build | Build fails on any server-only module in a client bundle; 0 secrets in NEXT_PUBLIC_ variables | Every pull request |

The Accessibility gate checks Celestial accessibility core v1.0 (WCAG 2.2 AA); it can change tool but is never skipped. Automated: A11Y-C1, A11Y-F1, A11Y-I1, A11Y-N1, A11Y-N2, A11Y-S1, A11Y-L2, A11Y-P1 (partly). Manual pass before release: A11Y-K1, A11Y-G1, A11Y-R1, A11Y-M1, A11Y-O1, A11Y-V1, A11Y-E1, A11Y-U1, A11Y-L1 — keyboard-only run, screen reader on each journey step, 200% zoom and 320px width, reduced motion, captions on any media. Requirement IDs come from the design and experience skills this code builds. This layer owns: **A11Y-F1** A visible focus indicator on every interactive element, never hidden behind sticky bars (WCAG 2.4.7, 2.4.11); **A11Y-R1** Text works at 200% zoom, at 320px width, with increased text spacing and in either orientation (WCAG 1.4.4, 1.4.10, 1.4.12, 1.3.4); **A11Y-M1** Motion respects the reduced-motion setting; anything moving for over 5 seconds can be paused; nothing flashes more than 3 times a second (WCAG 2.2.2, 2.3.1, 2.3.3 (AAA, advised)); **A11Y-O1** Tooltips and pop-overs shown on hover or focus can be dismissed, hovered and stay until dismissed (WCAG 1.4.13); **A11Y-I1** Images, icons and charts have text alternatives (empty for decoration); text is never an image (WCAG 1.1.1, 1.4.5); **A11Y-V1** Video and audio have captions, transcripts or audio description; nothing plays sound automatically for over 3 seconds (WCAG 1.2.1, 1.2.2, 1.2.3, 1.2.4, 1.2.5, 1.4.2); **A11Y-K1** Every action works by keyboard in a logical order, with no keyboard traps; single-key shortcuts can be turned off or remapped (WCAG 2.1.1, 2.1.2, 2.1.4, 2.4.3); **A11Y-G1** Nothing is drag-, gesture- or motion-only: each has a single tap or click alternative, and actions fire on release so they can be cancelled (WCAG 2.5.1, 2.5.2, 2.5.4, 2.5.7); **A11Y-N1** Every page has a clear title, headings, landmarks and a skip link, and can be found more than one way (WCAG 2.4.1, 2.4.2, 2.4.5, 2.4.6); **A11Y-N2** Controls have visible labels and instructions; links say where they go; the accessible name contains the visible label (WCAG 2.4.4, 2.5.3, 3.3.2); **A11Y-S1** Status, results and errors are announced to screen readers (WCAG 4.1.3); **A11Y-E2** Never ask for the same information twice in one flow; personal fields declare their purpose so they can be autofilled (WCAG 3.3.7, 1.3.5); **A11Y-U1** Focusing or changing a field never moves the person somewhere else or submits without warning (WCAG 3.2.1, 3.2.2); **A11Y-W1** Time limits warn first and can be extended (WCAG 2.2.1); **A11Y-L2** The page language, and any passage in another language, is declared in code (WCAG 3.1.1, 3.1.2); **A11Y-P1** Structure, order, names, roles and states are in the code: native elements first, ARIA only following the WAI-ARIA patterns (WCAG 1.3.1, 1.3.2, 4.1.2).

## Workflow
- Branching: Trunk-based: short-lived branches off main, squash-merged within two days.

**Review checklist**
- Correctness: does it do what the issue asks, including edge cases?
- Readability: could a new teammate change it safely?
- Architecture: is it in the right place, with the right boundaries?
- Security: inputs, secrets, permissions, dependencies
- Performance: budgets, queries, bundle size
- Tests fail when the code is broken (flip a condition and re-run)
- One approving review; two for auth, payments, data deletion or any new server action
- Reviewer checks each new 'use client' boundary and each revalidate call

**Definition of done**
- Acceptance criteria met and demoed on the preview link
- Tests added for new behaviour and every state
- Accessibility and performance gates green
- Analytics events named from the experience skill
- Docs or changelog updated when behaviour changes
- New server actions have a test for invalid input and for a signed-out caller

**Release**
- Small pull requests (aim for under 400 changed lines)
- CI green before review
- Squash-merge to main; main is always deployable
- Every release has a written rollback path
- Merge to main deploys to production; risky changes ship behind feature flags
- Database migrations run before the deploy and stay backwards compatible for one release

**Incidents**
- Roll back by promoting the previous deployment; migrations are forward-only, so ship a fix migration if needed
- Write a blameless note within 48 hours: what happened, impact, fix, prevention

## Overrides of the engineering core
- Performance budget: Measured on first-load JS from the production build, not the dev server — Dev bundles include tooling and misstate what users download.

## Examples
### Validated server action (`src/features/profile/actions.ts`)

```ts
'use server';
import { z } from 'zod';
import { revalidatePath } from 'next/cache';
import { requireUser } from '@/server/auth';
import { db, profiles } from '@/server/db';
import { eq } from 'drizzle-orm';

const Input = z.object({ displayName: z.string().trim().min(1).max(60) });

export type State = { error?: string; ok?: boolean };

export async function updateProfile(_prev: State, form: FormData): Promise<State> {
  const user = await requireUser();
  const parsed = Input.safeParse({ displayName: form.get('displayName') });
  if (!parsed.success) return { error: 'Enter a name between 1 and 60 characters.' };

  await db.update(profiles).set(parsed.data).where(eq(profiles.userId, user.id));
  revalidatePath('/settings/profile');
  return { ok: true };
}
```

## Further reading
- [Next.js documentation](https://nextjs.org/docs) — App Router, server actions, caching and the route file conventions.
- [React documentation](https://react.dev/learn) — Server and client component model and the hooks used in forms.
- [Web Vitals](https://web.dev/articles/vitals) — What LCP, INP and CLS measure and how the budget thresholds were chosen.
Pliki w paczce (4)
  • AGENTS.md 8 KB
  • README.md 2 KB
  • SKILL.md 14 KB
  • rules/nextjs-app-engineering.mdc 5 KB

Wersje

W bazie nie ma innych skilli o nazwie nextjs-app-engineering.

Migawka bazy z 13.11.2026 · wersja paczki 7d727267c90f (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 1 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100react-web-app-engineering
    Wspiera pisanie, testowanie i wydawanie aplikacji webowej w React, TypeScript, Tailwind CSS i Vitest.
  • 100angular-app-engineering
    Prowadzi budowę i wdrażanie aplikacji webowej w Angularze z TypeScript, SCSS i Vitest, także przy zamianie projektu graficznego na kod.
  • 91stack-nextjs
    Opisuje konwencje Next.js App Router: strony, trasy API, komponenty, Tailwind i testy Playwright w tym repozytorium.
  • 90nextjs-16
    Wspiera budowę aplikacji Next.js 16: Turbopack, App Router, Cache Components, proxy.ts i migrację z wersji 15.
  • 90nextjs-rules
    Podaje zasady i komendy sprawdzające dla kodu Next.js, React, TypeScript i Tailwind przy pisaniu lub przeglądzie kodu.
  • 100nextjs-testing
    Konfiguruje i pisze testy dla Next.js App Router: Vitest z React Testing Library dla komponentów i logiki serwerowej oraz Playwright dla przepływów end-to-end.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.