Przejdź do treści
Biblioteka skilli
Programowanie · Integracja z narzędziem

nextjs-integration

/nextjs-integration

Pokazuje, jak podłączyć @kavo/next do Next.js App Router: createKavoHandler, encje, operacje własne i eksport OpenAPI.

Repozytorium
kavo ↗
Licencja
MIT
Ostatnia zmiana repozytorium
17.10.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
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

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

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Pokazuje, jak podłączyć @kavo/next do Next.js App Router: createKavoHandler, encje, operacje własne i eksport OpenAPI.

Oryginalny opis (EN)

How to wire @kavo/next into an app's Next.js App Router — createKavoHandler, entity wiring, custom operations, and OpenAPI export. Use when a user is integrating Kavo into their own Next.js app, not when changing @kavo/next's own source (see docs/integrations/frameworks/nextjs.md, which this mirrors).

Jak działa

  1. The three pieces every integration needs
  2. Custom operations
  3. Overriding a generated route
  4. Things to check when something doesn't route or build
  5. Reference
Sekcje z nagłówków SKILL.md, w oryginale · 140 linii, 765 słów
Podgląd SKILL.md
---
name: nextjs-integration
description: How to wire @kavo/next into an app's Next.js App Router — createKavoHandler, entity wiring, custom operations, and OpenAPI export. Use when a user is integrating Kavo into their own Next.js app, not when changing @kavo/next's own source (see docs/integrations/frameworks/nextjs.md, which this mirrors).
---

# Integrating `@kavo/next`

`@kavo/next` binds Kavo to the Next.js App Router: `createKavoHandler` turns
one or more `createCrud` results into `GET`/`POST`/`PUT`/`PATCH`/`DELETE`
route-handler exports for a catch-all route. There's no decorator, no DI
container, and no dependency on `@kavo/nest` — App Router route handlers are
plain functions over the Fetch API's `Request`/`Response`.

## The three pieces every integration needs

1. **Wire entities where the app's Kavo setup lives** — call `createCrud`
   directly, once per entity, same as with any other framework binding:

   ```ts
   // kavo.ts
   import { createKavo } from "@kavo/core";
   import { createInfrastructure } from "@kavo/typeorm";
   import { dataSource } from "./data-source";
   import { User } from "./user.entity";

   const kavo = createKavo({ infrastructure: createInfrastructure(dataSource) });
   export const users = kavo.createCrud(User, { filter: { fields: ["id", "email"] } });
   ```

   Any ORM adapter works the same way here as with `@kavo/nest` —
   `@kavo/typeorm`, `@kavo/prisma`, `@kavo/mongoose`, `@kavo/mikroorm` all
   produce a plain `createCrud` result with nothing framework-specific.

2. **Mount the catch-all route** — one file, one call:

   ```ts
   // app/api/[...kavo]/route.ts
   import { createKavoHandler } from "@kavo/next";
   import { users, projects } from "../../../kavo";

   export const { GET, POST, PUT, PATCH, DELETE } = createKavoHandler({ users, projects });
   ```

   The first path segment resolves the entity by its key in this map
   (`users` → the `users` service); the rest resolves the operation by
   matching the request's method and remaining segments against that
   entity's own operation registry — the same registry `@kavo/nest`'s
   `@Kavo` decorator reads. An unknown entity key, or a method/segment
   combination no enabled operation resolves to, answers `404` — never
   `500`, never a bare `405` (see [ADR-0054](../../../docs/internals/adr/0054-next-resolves-routes-at-request-time.md)
   for why resolution happens at request time).

   Instead of re-listing every entity in a map, `createKavoHandler` also
   accepts the root `KavoInstance` directly and auto-builds the map from
   every `createCrud` call made against it:

   ```ts
   export const { GET, POST, PUT, PATCH, DELETE } = createKavoHandler(kavo);
   ```

   The key is `entityName` with only its first character lowercased
   (`User` → `user`) — no pluralization, since guessing a plural would
   just relocate the surprise. Want a different key? Use the explicit map
   instead; both forms dispatch identically and the explicit form is
   unaffected (see ADR-0054's amendment, issue #457).

3. **Optionally export OpenAPI schemas** — `buildKavoSchemas` is the
   `@kavo/next` equivalent of `@kavo/nest`'s `registerKavoSchemas`, built
   without `@nestjs/swagger`:

   ```ts
   // app/api/openapi.json/route.ts
   import { buildKavoSchemas } from "@kavo/next";
   import { users, projects } from "../../../kavo";

   export function GET() {
     const { schemas } = buildKavoSchemas({ users, projects });
     return Response.json({
       openapi: "3.1.0",
       info: { title: "My API", version: "1.0.0" },
       paths: {},
       components: { schemas },
     });
   }
   ```

   `paths` is left to the caller — `resolveRoute`/`matchRoute` are exported
   for a caller who wants a full `paths` document by walking
   `engine.registry.all()`.

## Custom operations

A custom operation (`operations.<id>` outside the standard eight) dispatches
exactly like the standard eight — same registry, same `meta.routes`
convention:

```ts
export const books = createCrud(Book, {
  operations: {
    markPaidOne: {
      handler: {/* ... */},
      meta: { routes: { method: "POST", path: ":id/mark-paid" } },
    },
  },
});
```

`POST /api/books/:id/mark-paid` reaches it through the same catch-all route.

## Overriding a generated route

There's no class to override here, unlike `@kavo/nest`'s manual-method-wins.
A caller who wants a genuinely custom implementation wins the way Next.js
already resolves any two routes that could match one request: add a sibling,
more specific route file. `app/api/books/[id]/mark-paid/route.ts` is matched
by Next.js before `[...kavo]` ever runs — no Kavo-side config needed.

## Things to check when something doesn't route or build

- **`next` is an optional peerDependency** — nothing in `@kavo/next` imports
  it at runtime; route handlers only need the Fetch API globals. Make sure
  `@kavo/core` plus the entity's ORM adapter peer are installed alongside it.
- **Next.js 15+ only** — `params` in a route handler's second argument is
  always a `Promise` (the App Router route-handler type validator requires
  this shape under `next build`). Next.js 14 handed `params` synchronously;
  this binding doesn't support it.
- **Minifier-renamed marker classes** — a production build's minifier can
  rename JS classes, which breaks an ORM adapter's marker-class name matching
  (`@kavo/prisma`'s, in particular) unless each marker's runtime `.name` is
  pinned explicitly. See `examples/next-prisma/entities/author/author.entity.ts`
  for the one-line fix.
- **Not yet supported**: bulk (`*Many`) operation dispatch through this
  binding (arrives once engine/registry support lands — it's a config change
  on the entity, not a `@kavo/next` change); SSE, GraphQL, and MCP glue for
  Next.js aren't part of this binding.

## Reference

`examples/next-prisma` is a full reference app: standard CRUD, a custom
operation, filtering/sorting/include, and the OpenAPI export route, wired
against `@kavo/prisma`. `docs/integrations/frameworks/nextjs.md` is the
canonical doc this skill mirrors — update both together if the binding's
behavior changes.

Wersje

W bazie nie ma innych skilli o nazwie nextjs-integration.

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

Pobrania w ostatnich 30 dniach: 0 · ranking

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

Podobne skille

  • 100kavo-decorator
    Opisuje, co generuje dekorator @Kavo(Entity, config?) i jak go konfigurować oraz nadpisywać: tabela tras, EntityConfig, ręczne metody, @Override i własne trasy.
  • 100swagger
    Wyjaśnia dodanie dokumentacji Swagger i OpenAPI do aplikacji NestJS, wskazując, co powstaje samo, a co trzeba dopisać ręcznie.
  • 95auth0-nextjs
    Dodaje do Next.js logowanie, wylogowanie, chronione strony i middleware przez @auth0/nextjs-auth0, w App Router i Pages Router.
  • 100nextjs-app-router
    Stosuje dobre praktyki Next.js App Router: Server Components, Server Actions, wzorce routingu i strategie pobierania danych.
  • 95nextjs-app-router
    Pomaga budować aplikacje Next.js 13+ z App Routerem, układami, stanami ładowania i streamingiem.
  • 100nextjs
    Zbiera wiedzę o Next.js 15+: App Router, Server Components, API Routes, Server Actions i optymalizacja wydajności.

Uwagi i zgłoszenia

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