updated docs
This commit is contained in:
@@ -11,99 +11,23 @@ blog/archive system (collections under an archive page, listing, pagination).
|
||||
|
||||
---
|
||||
|
||||
## Before you start
|
||||
|
||||
The `git.intecion.net` server is internal — you'll only see the code and the
|
||||
package once you're signed in to your Intecion account. Every installation method
|
||||
needs your personal access token. Without it you'll get a 404 or an
|
||||
"Unauthorized" error.
|
||||
|
||||
You generate the token once. It's tied to your account — don't ask anyone for
|
||||
theirs, and don't put it in any file that ends up in a repository.
|
||||
|
||||
### Generate a token
|
||||
|
||||
1. Sign in to Gitea → click your avatar → **Settings**.
|
||||
2. **Applications → Generate New Token**.
|
||||
3. Name it (e.g. `ipal-kit-install`) and select the scope:
|
||||
- `read:package` — if you only install the plugin in projects,
|
||||
- `write:package` — additionally, if you'll publish new versions.
|
||||
4. Click **Generate**. Copy the token now — Gitea shows it only once.
|
||||
|
||||
### Store the token in your environment
|
||||
|
||||
Don't paste the token straight into project files. Keep it in an environment
|
||||
variable, so your install config carries no secret. How you set it depends on
|
||||
your system:
|
||||
|
||||
**macOS** (default shell is zsh):
|
||||
```bash
|
||||
echo 'export GITEA_TOKEN=paste_your_token_here' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
**Linux / Ubuntu** (default shell is bash):
|
||||
```bash
|
||||
echo 'export GITEA_TOKEN=paste_your_token_here' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
**Windows (PowerShell)** — set it permanently for your user, then open a new
|
||||
terminal so it takes effect:
|
||||
```powershell
|
||||
setx GITEA_TOKEN "paste_your_token_here"
|
||||
```
|
||||
|
||||
> On Windows, `setx` writes the variable but does **not** affect the current
|
||||
> window — close it and open a new PowerShell for the token to be visible.
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
There are two routes. Pick **Route A** if you just want to use the plugin in a
|
||||
project — it's faster and versioned. Choose **Route B** only when you need a
|
||||
specific, unreleased commit straight from the repository.
|
||||
The plugin is published to a **public package registry** on the company Gitea.
|
||||
Installing it needs no token — just point the `@intecion` scope at the registry.
|
||||
|
||||
### Route A — from the registry (recommended)
|
||||
|
||||
The plugin is published to the package registry in Gitea. You pull a ready-built
|
||||
package and build nothing locally.
|
||||
|
||||
**1. Configure the registry.** Add these two lines to an `.npmrc` file:
|
||||
**1. Point the scope at the registry.** Add this line to an `.npmrc` file in your
|
||||
project (or to `~/.npmrc` to apply it everywhere):
|
||||
|
||||
```
|
||||
@intecion:registry=https://git.intecion.net/api/packages/IntecionSoftware/npm/
|
||||
//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN}
|
||||
```
|
||||
|
||||
You can put this file **in the project directory** (applies to that project) or
|
||||
**globally** (applies everywhere). The global location differs by system:
|
||||
|
||||
| System | Global `.npmrc` path |
|
||||
|---|---|
|
||||
| macOS | `~/.npmrc` (i.e. `/Users/you/.npmrc`) |
|
||||
| Linux / Ubuntu | `~/.npmrc` (i.e. `/home/you/.npmrc`) |
|
||||
| Windows | `%USERPROFILE%\.npmrc` (i.e. `C:\Users\you\.npmrc`) |
|
||||
|
||||
Fastest way to create the global file:
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
npm config set @intecion:registry https://git.intecion.net/api/packages/IntecionSoftware/npm/
|
||||
```
|
||||
```powershell
|
||||
# Windows (PowerShell) — same command, npm handles the path
|
||||
npm config set @intecion:registry https://git.intecion.net/api/packages/IntecionSoftware/npm/
|
||||
```
|
||||
|
||||
Then add the auth line manually (npm config doesn't set tokens with variables).
|
||||
Because the token lives in the `${GITEA_TOKEN}` variable, the file holds no
|
||||
secret — you can safely commit a project-level `.npmrc`.
|
||||
|
||||
> **Windows note:** the `${GITEA_TOKEN}` syntax in `.npmrc` is expanded by npm/pnpm
|
||||
> itself, not by the shell — so it works the same on Windows as on macOS/Linux,
|
||||
> as long as you set the variable with `setx` (see above).
|
||||
Only packages starting with `@intecion/` go to Gitea. Everything else
|
||||
(`react`, `next`, `@payloadcms/*`, …) still comes from the public npm registry —
|
||||
this line is a scoped override, not a change of your default registry. The file
|
||||
holds no secret, so you can commit it (and you should — your deployment needs it
|
||||
too).
|
||||
|
||||
**2. Install:**
|
||||
|
||||
@@ -111,28 +35,25 @@ secret — you can safely commit a project-level `.npmrc`.
|
||||
pnpm add @intecion/ipal-kit
|
||||
```
|
||||
|
||||
### Route B — straight from the repository
|
||||
That's it. No token, no login — the registry is public for reads.
|
||||
|
||||
pnpm clones the repository and uses the pre-built output. There's no `gitea:`
|
||||
shorthand — give the full address.
|
||||
### Why the registry, not a git install
|
||||
|
||||
Over HTTPS with your token:
|
||||
You *can* install straight from the repo
|
||||
(`pnpm add git+https://git.intecion.net/IntecionSoftware/ipal-kit.git`), and for a
|
||||
quick throwaway test it works. But prefer the registry for real projects:
|
||||
|
||||
```bash
|
||||
pnpm add git+https://$GITEA_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git
|
||||
```
|
||||
- **Client components resolve correctly.** A git install unpacks into a
|
||||
commit-hashed path (`.pnpm/@intecion+ipal-kit@git+https…#hash/…`) that breaks
|
||||
Next.js's React Client Manifest — the consent banner, analytics, and Turnstile
|
||||
components fail at runtime with "Could not find the module … in the React
|
||||
Client Manifest". The registry unpacks to a clean `node_modules/@intecion/…`
|
||||
path, so this doesn't happen.
|
||||
- **Versioning.** `pnpm` sees a real version number, so a version bump cleanly
|
||||
replaces the old one — no cache-clearing dance.
|
||||
|
||||
Or over SSH, if you have a key added in Gitea:
|
||||
|
||||
```bash
|
||||
pnpm add git+ssh://[email protected]:IntecionSoftware/ipal-kit.git
|
||||
```
|
||||
|
||||
Append a specific version after `#` to pin to a release:
|
||||
|
||||
```bash
|
||||
pnpm add git+https://$GITEA_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git#v1.0.0
|
||||
```
|
||||
Keep the git install only for pulling a specific unreleased commit during
|
||||
plugin development.
|
||||
|
||||
---
|
||||
|
||||
@@ -146,6 +67,10 @@ pnpm add @payloadcms/[email protected] @payloadcms/[email protected] \
|
||||
nodemailer lucide-react slugify server-only
|
||||
```
|
||||
|
||||
> **Match `lucide-react` to the plugin.** The plugin uses `lucide-react@^0.400.0`.
|
||||
> If your project pulls a different major (e.g. `1.x`), you end up with two copies
|
||||
> and confusing type errors. Pin your project to the same range.
|
||||
|
||||
From here, the guide takes over: **[docs/getting-started.md](./docs/getting-started.md)** —
|
||||
from an empty project to a working site.
|
||||
|
||||
@@ -153,16 +78,25 @@ from an empty project to a working site.
|
||||
|
||||
## Publishing a new version
|
||||
|
||||
This section only applies if you develop the plugin itself and publish new
|
||||
versions. You'll need a token with the `write:package` scope.
|
||||
This section applies only if you develop the plugin itself. Publishing (unlike
|
||||
installing) **does** need a token, with the `write:package` scope.
|
||||
|
||||
In `~/.npmrc`:
|
||||
In `~/.npmrc` (path differs per OS — see the table below):
|
||||
|
||||
```
|
||||
//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN}
|
||||
```
|
||||
|
||||
Build, bump the version number, publish:
|
||||
Generate the token in Gitea → **Settings → Applications → Generate New Token**,
|
||||
scope `write:package`. Put it in the `GITEA_TOKEN` env var.
|
||||
|
||||
| System | Global `.npmrc` path |
|
||||
|---|---|
|
||||
| macOS | `~/.npmrc` |
|
||||
| Linux / Ubuntu | `~/.npmrc` |
|
||||
| Windows | `%USERPROFILE%\.npmrc` |
|
||||
|
||||
Then build and publish:
|
||||
|
||||
```bash
|
||||
pnpm clean && pnpm build
|
||||
@@ -170,8 +104,7 @@ npm version patch # 1.0.0 → 1.0.1
|
||||
npm publish
|
||||
```
|
||||
|
||||
Bump the version on every release — that way pnpm always sees the new package and
|
||||
nobody gets stuck on a stale one from the cache.
|
||||
Full checklist and troubleshooting: **[docs/publishing.md](./docs/publishing.md)**.
|
||||
|
||||
---
|
||||
|
||||
@@ -189,11 +122,10 @@ Everything lives in the **[docs/](./docs)** directory. To get started:
|
||||
|
||||
| What you see | What's wrong |
|
||||
|---|---|
|
||||
| `404` or `Unauthorized` on `pnpm add @intecion/...` | no token in `.npmrc`, a wrong token, or you don't have access to the organization in Gitea |
|
||||
| `404` when installing from the `.git` address | you're not signed in, the token is missing from the address, or you lack access to the repository |
|
||||
| `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` | an attempt to build on install from git — report it to whoever publishes the plugin |
|
||||
| old code after reinstalling | cache: run `pnpm store prune`, then remove `.next` and `node_modules/@intecion` |
|
||||
| `404` on `pnpm add @intecion/...` | the `@intecion:registry` line is missing from `.npmrc` — the install went to public npm instead of Gitea |
|
||||
| `Could not find the module … in the React Client Manifest` | installed from git, not the registry — reinstall from the registry (clean path) |
|
||||
| two versions of `lucide-react` | your project pins a different major than the plugin's `^0.400.0` — align them |
|
||||
| `missing secret key … to secure Payload` | `PAYLOAD_SECRET` isn't set in the runtime environment (not a plugin issue) |
|
||||
|
||||
If you get stuck, check the troubleshooting table above, see
|
||||
**[docs/publishing.md](./docs/publishing.md)** for distribution issues, or message
|
||||
the team that maintains the plugin.
|
||||
If you get stuck, see **[docs/publishing.md](./docs/publishing.md)** or message the
|
||||
team that maintains the plugin.
|
||||
+3
-1
@@ -95,7 +95,7 @@ export default buildConfig({
|
||||
| `@intecion/ipal-kit/server` | runtime server-only (sendEmail, verifyTurnstile, submitForm) | Server Actions / route handlers |
|
||||
| `@intecion/ipal-kit/client` | komponenty client (consent, Turnstile, Analytics) | `'use client'` |
|
||||
| `@intecion/ipal-kit/rsc` | RenderBlocks (RSC) | server component |
|
||||
| `@intecion/ipal-kit/next/middleware` | locale middleware | middleware.ts / proxy.ts |
|
||||
| `@intecion/ipal-kit/next/middleware` | locale middleware (import bez zmian) | `proxy.ts` (Next 16; dawniej `middleware.ts`) |
|
||||
|
||||
## Moduły
|
||||
|
||||
@@ -118,6 +118,8 @@ export default buildConfig({
|
||||
Nowy projekt krok po kroku: [getting-started.md](./getting-started.md)
|
||||
Referencja wdrożenia frontu: [frontend-setup.md](./frontend-setup.md)
|
||||
Wydawanie nowych wersji wtyczki: [publishing.md](./publishing.md)
|
||||
Jak komendy łączą się z Gitea (dla instalujących): [gitea-commands.md](./gitea-commands.md)
|
||||
Working with a project repo on Gitea (clone/pull/push): [gitea-workflow.md](./gitea-workflow.md) · [🇵🇱 PL](./gitea-workflow.pl.md)
|
||||
|
||||
## Zasady dla wszystkich modułów
|
||||
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
# Jak komendy rozmawiają z git.intecion.net
|
||||
|
||||
Ten plik tłumaczy, co robi każda komenda, gdy instalujesz `@intecion/ipal-kit`.
|
||||
Rejestr pakietów jest **publiczny do odczytu** — instalacja nie wymaga tokenu.
|
||||
Token jest potrzebny tylko przy publikowaniu nowych wersji (patrz
|
||||
[publishing.md](./publishing.md)).
|
||||
|
||||
## Rejestr scoped — co to znaczy
|
||||
|
||||
W `.npmrc` masz jedną linię:
|
||||
|
||||
```
|
||||
@intecion:registry=https://git.intecion.net/api/packages/IntecionSoftware/npm/
|
||||
```
|
||||
|
||||
To reguła: „pakiety zaczynające się od `@intecion/` pobieraj z tego adresu".
|
||||
**Nie zmienia** domyślnego rejestru — wszystko inne (`react`, `next`,
|
||||
`@payloadcms/*`) dalej idzie z publicznego npm. To override dla jednego scope,
|
||||
nie przełączenie całego źródła.
|
||||
|
||||
Dlatego mieszana instalacja działa bez konfliktu:
|
||||
- `@intecion/ipal-kit` → Gitea
|
||||
- `react`, `payload`, `lucide-react` → npm
|
||||
|
||||
## Komenda po komendzie
|
||||
|
||||
### edycja `.npmrc` (linia z registry)
|
||||
|
||||
**Co robi:** zapisuje regułę „scope `@intecion` → rejestr Gitea". Nic nie
|
||||
pobiera — to plik konfiguracyjny, czytany dopiero przy instalacji.
|
||||
|
||||
**Rozmowa z serwerem:** żadna przy samym zapisie.
|
||||
|
||||
Ponieważ rejestr jest publiczny, ta linia **nie zawiera tokenu** — plik jest
|
||||
bezpieczny do zacommitowania i musi trafić do repo, żeby serwer deploymentu też
|
||||
wiedział, skąd brać `@intecion/*`.
|
||||
|
||||
### `pnpm add @intecion/ipal-kit`
|
||||
|
||||
**Co robi:** to komenda, która faktycznie łączy się z rejestrem.
|
||||
|
||||
Krok po kroku:
|
||||
1. pnpm widzi scope `@intecion` → sprawdza `.npmrc` → znajduje regułę „→ Gitea".
|
||||
2. Łączy się z rejestrem Gitea. Rejestr publiczny, więc **bez tokenu**.
|
||||
3. Rejestr odsyła metadane pakietu (wersje, adres `.tgz`).
|
||||
4. pnpm pobiera i rozpakowuje do `node_modules/@intecion/ipal-kit` — **czysta
|
||||
ścieżka**, bez hasha commita.
|
||||
|
||||
Ta czysta ścieżka jest ważna: komponenty klienta pluginu (baner zgód, analytics,
|
||||
Turnstile) rozwiązują się poprawnie tylko z niej. Instalacja z gita dawała
|
||||
pokręconą ścieżkę z hashem, która łamała React Client Manifest.
|
||||
|
||||
**Gdy to zawiedzie:**
|
||||
- `404` — brakuje linii `@intecion:registry` w `.npmrc`, więc pnpm poszedł do
|
||||
publicznego npm, gdzie pakietu nie ma. Sprawdź, czy `.npmrc` istnieje i ma tę
|
||||
linię.
|
||||
|
||||
### `pnpm install`
|
||||
|
||||
**Co robi:** odtwarza wszystkie zależności z `package.json` / lockfile, w tym
|
||||
`@intecion/ipal-kit`. Ta sama rozmowa z Gitea dla części `@intecion`, reszta z
|
||||
npm. Różnica względem `add`: `install` odtwarza to, co już zapisane, `add`
|
||||
dopisuje nowe.
|
||||
|
||||
## Sprawdzenie, czy rejestr odpowiada
|
||||
|
||||
Bez tokenu, publiczny endpoint:
|
||||
|
||||
```bash
|
||||
curl -s -o /dev/null -w "%{http_code}\n" \
|
||||
https://git.intecion.net/api/packages/IntecionSoftware/npm/@intecion%2Fipal-kit
|
||||
```
|
||||
|
||||
`200` → rejestr działa, pakiet dostępny. `404` → zła ścieżka/nazwa.
|
||||
|
||||
## Krótkie podsumowanie
|
||||
|
||||
| Komenda | Rozmawia z serwerem? | Token? | Po co |
|
||||
|---|---|---|---|
|
||||
| edycja `.npmrc` (registry) | nie | nie | reguła scope na później |
|
||||
| `pnpm add @intecion/ipal-kit` | tak | nie (publiczny) | pobiera pakiet |
|
||||
| `pnpm install` | tak (dla @intecion) | nie | odtwarza zależności |
|
||||
| `curl .../npm/@intecion%2F...` | tak | nie | test dostępności |
|
||||
|
||||
Publikowanie wersji (osobna rola, **wymaga** tokenu `write:package`):
|
||||
[publishing.md](./publishing.md).
|
||||
@@ -0,0 +1,116 @@
|
||||
# Wydawanie nowej wersji
|
||||
|
||||
|
||||
> **Instalacja jest publiczna** — rejestr Gitea pozwala pobierać pakiety bez
|
||||
> tokenu. Ten plik dotyczy **publikowania** nowych wersji, co wymaga tokenu
|
||||
> `write:package`. Instrukcja instalacji: główny [README](../README.md).
|
||||
|
||||
Dla osób rozwijających samą wtyczkę. Instalacja (dla użytkowników) jest w głównym
|
||||
[README](../README.md) — ten plik dotyczy publikowania kolejnych wersji do
|
||||
rejestru Gitea.
|
||||
|
||||
## package.json — co musi się zgadzać
|
||||
|
||||
Przed pierwszą publikacją sprawdź, że manifest jest poprawny — te pola były
|
||||
źródłem większości problemów przy dystrybucji:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@intecion/ipal-kit",
|
||||
"version": "1.0.0",
|
||||
"files": ["dist"],
|
||||
"main": "./dist/index.js",
|
||||
"types": "./dist/index.d.ts",
|
||||
"exports": { "...": "wszystkie subpath na ./dist/*.js i ./dist/*.d.ts" },
|
||||
"publishConfig": {
|
||||
"registry": "https://git.intecion.net/api/packages/IntecionSoftware/npm/"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Kontrola przed publikacją:
|
||||
|
||||
```bash
|
||||
grep -c '"exports"' package.json # 1 — jeden blok, nie dwa
|
||||
grep -c "git+https.*ipal-kit" package.json # 0 — brak self-reference
|
||||
grep '"import"' package.json | head -1 # ./dist/ — nie ./src/
|
||||
node -e "JSON.parse(require('fs').readFileSync('package.json','utf8'))" # bez błędu
|
||||
```
|
||||
|
||||
- **`exports` na `dist`, nie `src`** — jeden blok, wszystkie ścieżki na `./dist/`.
|
||||
- **jeden blok `exports`** — nie zostawiaj drugiego (np. w starym
|
||||
`publishConfig.exports`); dwa bloki rozjeżdżają rozwiązywanie modułów.
|
||||
- **brak self-reference** — pakiet nie może mieć siebie w `dependencies`.
|
||||
Wchodzi, gdy odpalisz `pnpm add` w katalogu wtyczki — **nigdy tego nie rób**.
|
||||
- **peer, nie dependencies** — `payload`, `next`, `react`,
|
||||
`@payloadcms/plugin-seo`, `@payloadcms/plugin-form-builder` w
|
||||
`peerDependencies`. W `dependencies` inaczej zaciągną drugą kopię Payloada.
|
||||
|
||||
## Rejestr — droga zalecana
|
||||
|
||||
Rejestr npm w Gitea. Pracownicy pobierają gotowy `dist`, nie budują u siebie.
|
||||
|
||||
**Token** z zakresem `write:package` (Gitea → Settings → Applications), w
|
||||
globalnym `.npmrc` (ścieżka zależna od systemu — patrz tabela w głównym
|
||||
[README](../README.md#route-a--from-the-registry-recommended); na Windows to
|
||||
`%USERPROFILE%\.npmrc`):
|
||||
|
||||
```
|
||||
//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN}
|
||||
```
|
||||
|
||||
**Wydanie:**
|
||||
|
||||
```bash
|
||||
pnpm clean && pnpm build
|
||||
npm version patch # 1.0.0 → 1.0.1 (minor/major wg zmian)
|
||||
npm publish
|
||||
```
|
||||
|
||||
Podnoś wersję przy każdym wydaniu — pnpm rozpoznaje pakiet po numerze, więc nowy
|
||||
numer znosi cały cykl czyszczenia pamięci podręcznej, który męczy przy
|
||||
zostawaniu na jednej wersji.
|
||||
|
||||
## Alternatywa — dystrybucja z repozytorium (bez rejestru)
|
||||
|
||||
Jeśli nie publikujesz do rejestru, a instalujesz bezpośrednio z Gitea
|
||||
(`git+https://...`), obowiązują dodatkowe reguły:
|
||||
|
||||
- **`dist/` musi być zacommitowany** w repozytorium — instalacja z git nie
|
||||
buduje pakietu. Buduj i commituj `dist` przed każdym wydaniem:
|
||||
```bash
|
||||
pnpm build
|
||||
git add -f dist/ # -f, jeśli .gitignore normalnie ignoruje dist
|
||||
git commit -m "build dist"
|
||||
git push
|
||||
```
|
||||
- **BRAK `prepare: pnpm build`** w package.json — inaczej pnpm próbuje budować
|
||||
przy instalacji i żąda `onlyBuiltDependencies`.
|
||||
- **sprawdzaj repozytorium, nie plik lokalny** — pnpm z git bierze stan repo:
|
||||
```bash
|
||||
git show origin/main:package.json | grep '"import"' | head -1 # ./dist/
|
||||
```
|
||||
Commit z nazwą „fix" nie znaczy, że poprawka jest w commicie.
|
||||
|
||||
## Weryfikacja po publikacji
|
||||
|
||||
W czystym projekcie testowym:
|
||||
|
||||
```bash
|
||||
pnpm store prune
|
||||
pnpm add @intecion/ipal-kit # albo git+https://... dla drogi repo
|
||||
node -e "console.log(require.resolve('@intecion/ipal-kit/next/middleware'))"
|
||||
```
|
||||
|
||||
Ostatnia komenda ma wypisać ścieżkę do `dist/exports/next-middleware.js` — nie
|
||||
błąd. Jeśli pokazuje `src/...ts`, główny `exports` wskazuje źródła zamiast builda.
|
||||
|
||||
## Diagnostyka
|
||||
|
||||
| Objaw | Przyczyna |
|
||||
|---|---|
|
||||
| `Cannot find module .../src/...ts` | główny `exports` na `src`; przy instalacji z git `publishConfig` jest ignorowane |
|
||||
| Turbopack „Module not found" mimo pliku na dysku | dwa bloki `exports`; Node bierze zły |
|
||||
| `ENOENT ...ipal-kit.tgz` | self-reference w `dependencies` |
|
||||
| `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` | `prepare` w package.json (droga repo) |
|
||||
| stary kod mimo reinstall | pamięć podręczna; podnieś wersję albo `pnpm store prune` + `rm -rf .next node_modules/@intecion` |
|
||||
@@ -91,20 +91,21 @@ export const i18nConfig = {
|
||||
} as const // as const — inaczej TS: locales nie pasuje do niepustej tuple
|
||||
```
|
||||
|
||||
Importuj w: payload.config (ipalKit({ i18n: i18nConfig })), middleware.ts.
|
||||
Importuj w: payload.config (ipalKit({ i18n: i18nConfig })), proxy.ts.
|
||||
Layout może czytać locale z payload config (config.localization.locales) —
|
||||
też jedno źródło.
|
||||
|
||||
## Middleware
|
||||
## Proxy (dawniej middleware)
|
||||
|
||||
> **Next 16:** konwencja `middleware.ts` jest deprecated na rzecz `proxy.ts`
|
||||
> (plik `proxy.ts`, funkcja `export function proxy`). Logika pluginu bez zmian —
|
||||
> `createLocaleMiddleware` działa tak samo, zmienia się tylko nazwa pliku i
|
||||
> funkcji po stronie projektu. Na razie `middleware.ts` działa z ostrzeżeniem.
|
||||
> funkcji po stronie projektu. Migracja jedną komendą:
|
||||
> `npx @next/codemod@canary middleware-to-proxy .`
|
||||
|
||||
|
||||
```ts
|
||||
// src/middleware.ts
|
||||
// src/proxy.ts
|
||||
import { NextResponse } from 'next/server'
|
||||
import type { NextRequest } from 'next/server'
|
||||
import { createLocaleMiddleware } from '@intecion/ipal-kit/next/middleware'
|
||||
@@ -112,16 +113,17 @@ import { i18nConfig } from '@/i18n.config'
|
||||
|
||||
const localeMiddleware = createLocaleMiddleware({ config: i18nConfig })
|
||||
|
||||
export function middleware(request: NextRequest) {
|
||||
export function proxy(request: NextRequest) {
|
||||
const result = localeMiddleware(request)
|
||||
if (result.type === 'next') return NextResponse.next()
|
||||
const response = NextResponse.redirect(result.location)
|
||||
response.cookies.set(result.cookie.name, result.cookie.value)
|
||||
// cookie tylko gdy jest zgoda na kategorię functional — inaczej undefined
|
||||
if (result.cookie) response.cookies.set(result.cookie.name, result.cookie.value)
|
||||
return response
|
||||
}
|
||||
|
||||
// matcher MUSI być inline (Next analizuje statycznie, nie wykonuje importów —
|
||||
// import DEFAULT_MIDDLEWARE_MATCHER byłby zignorowany → middleware łapie
|
||||
// import DEFAULT_MIDDLEWARE_MATCHER byłby zignorowany → proxy łapie
|
||||
// /admin /_next /api → 500)
|
||||
export const config = {
|
||||
matcher: ['/((?!api|admin|_next|.*\\..*).*)'],
|
||||
|
||||
+15
-5
@@ -187,10 +187,15 @@ export default { plugins: { '@tailwindcss/postcss': {} } }
|
||||
niego klasy komponentów pluginu nie powstaną i banner wyrenderuje się goły.
|
||||
Ścieżka jest relatywna do pliku CSS.
|
||||
|
||||
## 8. Middleware
|
||||
## 8. Proxy (dawniej middleware)
|
||||
|
||||
> **Next 16:** konwencja `middleware.ts` jest przestarzała — nazwa pliku to teraz
|
||||
> `proxy.ts`, a funkcja `proxy` zamiast `middleware`. Logika pluginu bez zmian:
|
||||
> `createLocaleMiddleware` działa tak samo. Migracja jednej komendy:
|
||||
> `npx @next/codemod@canary middleware-to-proxy .`
|
||||
|
||||
```ts
|
||||
// src/middleware.ts
|
||||
// src/proxy.ts
|
||||
import { NextResponse } from 'next/server'
|
||||
import type { NextRequest } from 'next/server'
|
||||
import { createLocaleMiddleware } from '@intecion/ipal-kit/next/middleware'
|
||||
@@ -198,23 +203,28 @@ import { i18nConfig } from '@/i18n.config'
|
||||
|
||||
const localeMiddleware = createLocaleMiddleware({ config: i18nConfig })
|
||||
|
||||
export function middleware(request: NextRequest) {
|
||||
export function proxy(request: NextRequest) {
|
||||
const result = localeMiddleware(request)
|
||||
if (result.type === 'next') return NextResponse.next()
|
||||
|
||||
const response = NextResponse.redirect(result.location)
|
||||
response.cookies.set(result.cookie.name, result.cookie.value)
|
||||
// cookie tylko gdy jest zgoda na kategorię functional — inaczej undefined
|
||||
if (result.cookie) response.cookies.set(result.cookie.name, result.cookie.value)
|
||||
return response
|
||||
}
|
||||
|
||||
// INLINE, nie import — Next analizuje ten obiekt statycznie i nie wykonuje
|
||||
// importów. Importowana stała zostanie zignorowana, middleware złapie /admin
|
||||
// importów. Importowana stała zostanie zignorowana, proxy złapie /admin
|
||||
// i /_next, i wszystko zwróci 500.
|
||||
export const config = {
|
||||
matcher: ['/((?!api|admin|_next|.*\\..*).*)'],
|
||||
}
|
||||
```
|
||||
|
||||
> Import z pluginu zostaje `@intecion/ipal-kit/next/middleware` — to nazwa
|
||||
> subpath eksportu w pakiecie, niezależna od tego, czy plik projektu nazywa się
|
||||
> `middleware.ts` czy `proxy.ts`.
|
||||
|
||||
## 9. Warstwa dostępu do danych
|
||||
|
||||
Next uruchamia `generateMetadata` i komponent strony niezależnie — `cache()`
|
||||
|
||||
+10
-5
@@ -69,13 +69,18 @@ fallback na `/{locale}` (root), zamiast dead-endu na 404.
|
||||
## Middleware — patrz osobno
|
||||
|
||||
Negocjacja locale + redirect na wejściu (`domena.com` → `/pl`) jest w
|
||||
`@intecion/ipal-kit/next/middleware`. Zobacz [middleware w tej sekcji](#middleware)
|
||||
`@intecion/ipal-kit/next/middleware`. Zobacz [proxy w tej sekcji](#proxy-dawniej-middleware)
|
||||
niżej.
|
||||
|
||||
## Middleware
|
||||
## Proxy (dawniej middleware)
|
||||
|
||||
> **Next 16:** plik nazywa się teraz `proxy.ts`, funkcja `proxy`. Import z
|
||||
> pluginu (`@intecion/ipal-kit/next/middleware`) bez zmian — to nazwa subpath
|
||||
> eksportu, niezależna od nazwy pliku projektu. Migracja:
|
||||
> `npx @next/codemod@canary middleware-to-proxy .`
|
||||
|
||||
```ts
|
||||
// middleware.ts (projekt klienta) — jedyna logika to podłączenie
|
||||
// proxy.ts (projekt klienta) — jedyna logika to podłączenie
|
||||
import { NextResponse } from 'next/server'
|
||||
import { createLocaleMiddleware, DEFAULT_MIDDLEWARE_MATCHER } from '@intecion/ipal-kit/next/middleware'
|
||||
|
||||
@@ -85,11 +90,11 @@ const i18nConfig = {
|
||||
}
|
||||
const localeMiddleware = createLocaleMiddleware({ config: i18nConfig })
|
||||
|
||||
export function middleware(req) {
|
||||
export function proxy(req) {
|
||||
const r = localeMiddleware(req)
|
||||
if (r.type === 'next') return NextResponse.next()
|
||||
const res = NextResponse.redirect(r.location)
|
||||
res.cookies.set(r.cookie.name, r.cookie.value)
|
||||
if (r.cookie) res.cookies.set(r.cookie.name, r.cookie.value)
|
||||
return res
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user