updated docs
This commit is contained in:
+3
-1
@@ -1,6 +1,8 @@
|
|||||||
# IPAL — Dokumentacja modułów
|
# IPAL — Dokumentacja modułów
|
||||||
|
|
||||||
**Stawiasz nowy projekt?** → [getting-started.md](./getting-started.md)
|
**Stawiasz nowy projekt?** → [install.md](./install.md) — instalacja (github/rejestr/tarball) i diagnostyka
|
||||||
|
|
||||||
|
Konfiguracja: [getting-started.md](./getting-started.md)
|
||||||
|
|
||||||
IPAL (Intecion Payload Advanced Library) to plugin do Payload CMS 3, który
|
IPAL (Intecion Payload Advanced Library) to plugin do Payload CMS 3, który
|
||||||
dostarcza logikę i konfigurację; projekt klienta zawiera tylko komponenty
|
dostarcza logikę i konfigurację; projekt klienta zawiera tylko komponenty
|
||||||
|
|||||||
@@ -97,6 +97,12 @@ też jedno źródło.
|
|||||||
|
|
||||||
## Middleware
|
## 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.
|
||||||
|
|
||||||
|
|
||||||
```ts
|
```ts
|
||||||
// src/middleware.ts
|
// src/middleware.ts
|
||||||
import { NextResponse } from 'next/server'
|
import { NextResponse } from 'next/server'
|
||||||
|
|||||||
@@ -1,5 +1,9 @@
|
|||||||
# Nowy projekt — krok po kroku
|
# Nowy projekt — krok po kroku
|
||||||
|
|
||||||
|
> **Instalacja:** najszybciej `pnpm add github:rasm-its/ipal-kit`. Pełne drogi
|
||||||
|
> (github / rejestr / tarball) i diagnostyka błędów — install.md.
|
||||||
|
|
||||||
|
|
||||||
Od pustego katalogu do działającej, wielojęzycznej strony z blokami, consentem i
|
Od pustego katalogu do działającej, wielojęzycznej strony z blokami, consentem i
|
||||||
formularzem. Kolejność jest istotna: kilka kroków zależy od poprzednich (schemat
|
formularzem. Kolejność jest istotna: kilka kroków zależy od poprzednich (schemat
|
||||||
bazy, importMap, kolejność wpięcia).
|
bazy, importMap, kolejność wpięcia).
|
||||||
|
|||||||
+118
@@ -0,0 +1,118 @@
|
|||||||
|
# Instalacja ipal-kit
|
||||||
|
|
||||||
|
Trzy drogi. Wybierz jedną i trzymaj się jej — mieszanie (raz git, raz rejestr,
|
||||||
|
raz tarball) to najczęstsze źródło błędów instalacji.
|
||||||
|
|
||||||
|
## Droga A — z GitHuba (zalecana dla zespołu)
|
||||||
|
|
||||||
|
Wymaga, żeby `dist/` był zacommitowany w repo (nie budowany u instalującego).
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pnpm add github:rasm-its/ipal-kit
|
||||||
|
# konkretny tag (stabilniej):
|
||||||
|
pnpm add github:rasm-its/ipal-kit#v1.0.0
|
||||||
|
```
|
||||||
|
|
||||||
|
Wymagania po stronie projektu:
|
||||||
|
|
||||||
|
1. **`onlyBuiltDependencies`** — pnpm blokuje skrypty build z paczek git.
|
||||||
|
Jeśli pakiet ma jakiekolwiek skrypty postinstall, dodaj w package.json
|
||||||
|
projektu:
|
||||||
|
```json
|
||||||
|
"pnpm": { "onlyBuiltDependencies": ["@intecion/ipal-kit"] }
|
||||||
|
```
|
||||||
|
(Jeśli plugin nie ma `prepare`/postinstall — patrz niżej — to niepotrzebne.)
|
||||||
|
|
||||||
|
2. **peer-zależności** — plugin ich nie zaciąga, projekt musi mieć:
|
||||||
|
```bash
|
||||||
|
pnpm add @payloadcms/[email protected] @payloadcms/[email protected] \
|
||||||
|
nodemailer lucide-react slugify server-only
|
||||||
|
```
|
||||||
|
|
||||||
|
Wymagania po stronie pluginu (raz, przy wydawaniu):
|
||||||
|
|
||||||
|
- **`dist/` w repo** — bo instalacja z git nie buduje. Zbuduj i zacommituj
|
||||||
|
`dist` przed każdym wydaniem.
|
||||||
|
- **BRAK `prepare: pnpm build`** w package.json — inaczej pnpm próbuje budować
|
||||||
|
przy instalacji i żąda `onlyBuiltDependencies`. Skoro `dist` jest w repo, build
|
||||||
|
jest zbędny.
|
||||||
|
- **główny `exports` wskazuje `dist`, nie `src`** — instalacja z git czyta
|
||||||
|
główny `exports` (publishConfig działa TYLKO przy `npm publish`, nie przy git).
|
||||||
|
Wszystkie ścieżki `./dist/*.js` i `./dist/*.d.ts`.
|
||||||
|
- **jeden blok `exports`** — nie zostawiaj `publishConfig.exports` obok głównego;
|
||||||
|
dwa bloki potrafią rozjechać rozwiązywanie modułów.
|
||||||
|
- **żadnej self-reference** — pakiet nie może mieć siebie w `dependencies`
|
||||||
|
(`"@intecion/ipal-kit": "git+..."`). Wchodzi, gdy odpalisz `pnpm add` w
|
||||||
|
katalogu pluginu — NIGDY tego nie rób.
|
||||||
|
|
||||||
|
## Droga B — GitHub Packages (rejestr)
|
||||||
|
|
||||||
|
Publikujesz zbudowany pakiet; instalujący pobiera gotowy `dist`, nie buduje.
|
||||||
|
|
||||||
|
Plugin — `publishConfig.registry` + token z `write:packages`:
|
||||||
|
```bash
|
||||||
|
echo "//npm.pkg.github.com/:_authToken=TOKEN" >> ~/.npmrc
|
||||||
|
npm version patch && npm publish
|
||||||
|
```
|
||||||
|
|
||||||
|
Projekt — `.npmrc` ze scope + token z `read:packages`:
|
||||||
|
```
|
||||||
|
@intecion:registry=https://npm.pkg.github.com
|
||||||
|
//npm.pkg.github.com/:_authToken=TOKEN
|
||||||
|
```
|
||||||
|
```bash
|
||||||
|
pnpm add @intecion/ipal-kit
|
||||||
|
```
|
||||||
|
|
||||||
|
Zaleta nad Drogą A: semver (koniec z ręcznym commitowaniem `dist`), `publishConfig`
|
||||||
|
działa (nie musisz ruszać głównego `exports`). Wada: token u każdego instalującego.
|
||||||
|
|
||||||
|
## Droga C — lokalny tarball (development, przekazanie pliku)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# w pluginie
|
||||||
|
pnpm build && pnpm pack --out ipal-kit.tgz
|
||||||
|
|
||||||
|
# w PROJEKCIE (nie w pluginie!)
|
||||||
|
pnpm add ~/sciezka/ipal-kit/ipal-kit.tgz
|
||||||
|
```
|
||||||
|
|
||||||
|
`--out ipal-kit.tgz` daje stałą nazwę — bez tego scope zamienia `/` na `-`
|
||||||
|
(`intecion-ipal-kit-1.0.0.tgz`).
|
||||||
|
|
||||||
|
## Twarde zasady (wyparzone w boju)
|
||||||
|
|
||||||
|
- **NIGDY `pnpm add ...ipal-kit...` w katalogu pluginu.** Tworzy self-reference,
|
||||||
|
która zatruwa każdą kolejną instalację. Zawsze w katalogu projektu. Sprawdzaj
|
||||||
|
`pwd` przed każdym `pnpm add`.
|
||||||
|
- **Sprawdzaj REPO, nie plik lokalny.** pnpm z git bierze stan repo. Po zmianie:
|
||||||
|
`git show origin/main:package.json | grep '"import"'` — musi pokazać `./dist/`.
|
||||||
|
Commit z nazwą "fix" nie znaczy, że fix jest w commicie.
|
||||||
|
- **Nie edytuj package.json `sed`em.** Rozjeżdża strukturę (dwa bloki exports).
|
||||||
|
Nadpisuj cały plik.
|
||||||
|
- **Zostajesz na 1.0.0? Czyść cache przy każdym reinstall:**
|
||||||
|
```bash
|
||||||
|
rm -rf node_modules/@intecion node_modules/.pnpm/*ipal-kit* .next
|
||||||
|
pnpm store prune && pnpm install
|
||||||
|
```
|
||||||
|
Publikacja z bumpem wersji (Droga B) to znosi.
|
||||||
|
- **Weryfikuj rozwiązanie modułu, nie tylko instalację:**
|
||||||
|
```bash
|
||||||
|
node -e "console.log(require.resolve('@intecion/ipal-kit/next/middleware'))"
|
||||||
|
```
|
||||||
|
Ma wypisać ścieżkę do `dist`, nie błąd. Jeśli pokazuje `src/...ts` → główny
|
||||||
|
`exports` wskazuje src (patrz Droga A).
|
||||||
|
|
||||||
|
## Diagnostyka — objaw → przyczyna
|
||||||
|
|
||||||
|
| Objaw | Przyczyna |
|
||||||
|
|---|---|
|
||||||
|
| `ERR_PNPM_FETCH_404` na `@scope/...` | pakiet nieopublikowany; użyto nazwy rejestrowej zamiast `github:` |
|
||||||
|
| `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` | `prepare` w package.json + brak `onlyBuiltDependencies` |
|
||||||
|
| `Cannot find module .../src/exports/X.ts` | główny `exports` wskazuje src; instalacja z git nie widzi publishConfig |
|
||||||
|
| `ENOENT ...ipal-kit-1.0.0.tgz` przy instalacji | self-reference w dependencies pluginu |
|
||||||
|
| Turbopack „Module not found" mimo pliku na dysku | dwa bloki exports w package.json; Node bierze zły |
|
||||||
|
| `pnpm add` przeszło, pakietu brak w node_modules | instalacja do złego katalogu, albo przerwana — sprawdź `pwd` |
|
||||||
|
| stary kod mimo reinstall (1.0.0) | cache; `pnpm store prune` + `rm -rf .next` |
|
||||||
|
|
||||||
|
Po instalacji — konfiguracja pluginu: getting-started.md.
|
||||||
Generated
+5
-5
Reference in New Issue
Block a user