updated docs
This commit is contained in:
+3
-1
@@ -1,6 +1,8 @@
|
||||
# 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
|
||||
dostarcza logikę i konfigurację; projekt klienta zawiera tylko komponenty
|
||||
|
||||
@@ -97,6 +97,12 @@ też jedno źródło.
|
||||
|
||||
## 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
|
||||
// src/middleware.ts
|
||||
import { NextResponse } from 'next/server'
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 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
|
||||
formularzem. Kolejność jest istotna: kilka kroków zależy od poprzednich (schemat
|
||||
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