From fd1ab5e17e479cc600e4838f7ed97f283ed1d2d9 Mon Sep 17 00:00:00 2001 From: Admin Date: Sun, 2 Aug 2026 21:41:24 +0000 Subject: [PATCH] Update README.md --- README.md | 193 +++++++++++++++++++++++++++--------------------------- 1 file changed, 96 insertions(+), 97 deletions(-) diff --git a/README.md b/README.md index f85d4d3..93973c3 100644 --- a/README.md +++ b/README.md @@ -1,160 +1,159 @@ # @intecion/ipal-kit -Intecion Payload Advanced Library — plugin do Payload CMS 3. Dostarcza i18n -(routing per-locale, hreflang, przełącznik języka), SEO (metadane, canonical, -sitemapa, robots), formularze (Turnstile, rate limit, walidacja), consent mode, -analytics (GA4/GTM), oraz system bloga/archiwów (kolekcje pod stroną-archiwum, -listing, paginacja). +Intecion Payload Advanced Library — a plugin for Payload CMS 3. -Repozytorium: https://git.intecion.net/IntecionSoftware/ipal-kit -(dostęp tylko dla zalogowanych pracowników Intecion). +Provides internationalization (per-locale routing, hreflang, language switcher), +SEO (metadata, canonical, sitemap, robots), forms (Turnstile, rate limiting, +validation), consent management (consent mode), analytics (GA4/GTM), and a +blog/archive system (collections under an archive page, listing, pagination). + +**Repository:** https://git.intecion.net/IntecionSoftware/ipal-kit --- -## Instalacja +## Before you start -> **Serwer jest prywatny.** Zarówno kod, jak i pakiet w Gitea są widoczne tylko -> po zalogowaniu. Każdy sposób instalacji wymaga tokenu dostępu (PAT) z konta -> pracownika. Bez niego instalacja zwróci 404 albo błąd autoryzacji. +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. -### Krok 1 — token dostępu (raz na osobę) +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. -W Gitea: **Ustawienia → Aplikacje → Wygeneruj token dostępu**. Nadaj zakresy: -- `read:package` — do instalacji (wystarczy pracownikowi) -- `write:package` — dodatkowo, jeśli będziesz publikować wydania +### Generate a token -Skopiuj token (pokazuje się raz). +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. -### Krok 2 — wybierz drogę instalacji +### Store the token in your environment -Dwie drogi. **A (rejestr Gitea)** jest zalecana dla zespołu — daje wersjonowanie -i szybką instalację gotowego builda. **B (bezpośrednio z git)** nie wymaga -publikowania, ale buduje/pobiera z repo. +Don't paste the token straight into project files. Keep it in an environment +variable, so your install config carries no secret. + +```bash +# add to ~/.zshrc (or ~/.bashrc) +export GITEA_TOKEN=paste_your_token_here +``` + +Reload your shell (`source ~/.zshrc`) or open a new terminal window. --- -## Droga A — rejestr npm w Gitea (zalecana) +## Installation -Gitea ma wbudowany rejestr npm. Publikujesz zbudowany pakiet, pracownicy pobierają -gotowy `dist` — bez budowania u siebie. +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. -### Konfiguracja u pracownika (instalacja) +### Route A — from the registry (recommended) -`.npmrc` w projekcie **albo** globalnie (`~/.npmrc`): +The plugin is published to the package registry in Gitea. You pull a ready-built +package and build nothing locally. + +**1. Configure the registry.** Create an `.npmrc` file in your project directory +(or add these two lines to `~/.npmrc` to make it work globally): ``` @intecion:registry=https://git.intecion.net/api/packages/IntecionSoftware/npm/ //git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN} ``` -Token w zmiennej środowiskowej (bezpieczniej niż wpisany wprost — `.npmrc` można -wtedy nawet zacommitować): +Because the token lives in the `${GITEA_TOKEN}` variable, this file holds no +secret — you can safely commit it. -```bash -# ~/.zshrc -export GITEA_TOKEN=twój_token_z_gitea -``` - -Instalacja: +**2. Install:** ```bash pnpm add @intecion/ipal-kit ``` -### Publikacja (osoba wydająca) +### Route B — straight from the repository -W `package.json` pluginu (jest już ustawione): -```json -"publishConfig": { - "registry": "https://git.intecion.net/api/packages/IntecionSoftware/npm/" -} -``` +pnpm clones the repository and uses the pre-built output. There's no `gitea:` +shorthand — give the full address. -`~/.npmrc` z tokenem `write:package`: -``` -//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN} -``` +Over HTTPS with your token: -Wydanie: ```bash -pnpm clean && pnpm build -npm version patch # 1.0.0 → 1.0.1 -npm publish +pnpm add git+https://$GITEA_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git ``` -Zaleta rejestru: semver — pnpm zawsze widzi nową wersję, koniec z ręcznym -czyszczeniem cache. `publishConfig` działa poprawnie (exports z dist), nie musisz -ruszać głównego `exports`. +Or over SSH, if you have a key added in Gitea: ---- - -## Droga B — bezpośrednio z repozytorium git - -Bez publikowania. pnpm klonuje repo i bierze zacommitowany `dist`. - -### Uwierzytelnienie - -Serwer prywatny, więc git musi mieć dostęp. Dwie opcje: - -**SSH** (jeśli masz klucz w Gitea): ```bash pnpm add git+ssh://git@git.intecion.net:IntecionSoftware/ipal-kit.git ``` -**HTTPS z tokenem**: +Append a specific version after `#` to pin to a release: + ```bash -pnpm add git+https://TWÓJ_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git +pnpm add git+https://$GITEA_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git#v1.0.0 ``` -Konkretny tag (stabilniej niż główny branch): -```bash -pnpm add git+https://TWÓJ_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git#v1.0.0 -``` - -> Nie ma skrótu `gitea:` (jak `github:`). Zawsze pełny URL `git+https://` lub -> `git+ssh://`. - -### Wymagania po stronie repo (dla wydającego) - -Instalacja z git NIE buduje pakietu, więc: -- **`dist/` musi być zacommitowany** — zbuduj i zacommituj przed każdym wydaniem -- **BRAK `prepare: pnpm build`** w package.json — inaczej pnpm próbuje budować - i żąda `onlyBuiltDependencies` -- **główny `exports` wskazuje `dist`** (nie `src`) — instalacja z git czyta - główny exports, `publishConfig` jest ignorowane przy git - --- -## Po instalacji (obie drogi) +## Finish setting up your project -Dodaj peer-zależności — plugin ich nie zaciąga: +The plugin doesn't pull in the dependencies it shares with Payload — add them +yourself, in a version matching your Payload: ```bash pnpm add @payloadcms/plugin-seo@3.84.1 @payloadcms/plugin-form-builder@3.84.1 \ nodemailer lucide-react slugify server-only ``` -Konfiguracja pluginu, krok po kroku: [docs/getting-started.md](./docs/getting-started.md). +From here, the guide takes over: **[docs/getting-started.md](./docs/getting-started.md)** — +from an empty project to a working site. --- -## Dokumentacja +## Publishing a new version -Pełna dokumentacja w [docs/](./docs). Start: -- [docs/getting-started.md](./docs/getting-started.md) — od zera do działającego projektu -- [docs/install.md](./docs/install.md) — szczegóły instalacji i diagnostyka -- [docs/README.md](./docs/README.md) — spis modułów +This section only applies if you develop the plugin itself and publish new +versions. You'll need a token with the `write:package` scope. + +In `~/.npmrc`: + +``` +//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN} +``` + +Build, bump the version number, publish: + +```bash +pnpm clean && pnpm build +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. --- -## Diagnostyka instalacji +## Documentation -| Objaw | Przyczyna | +Everything lives in the **[docs/](./docs)** directory. To get started: + +- **[getting-started.md](./docs/getting-started.md)** — project setup, step by step +- **[install.md](./docs/install.md)** — more on installation and troubleshooting +- **[README.md](./docs/README.md)** — index of the plugin's modules + +--- + +## Something not working? + +| What you see | What's wrong | |---|---| -| `404` / `Unauthorized` przy `pnpm add @intecion/...` | brak/zły token w `.npmrc`, albo brak dostępu do organizacji w Gitea | -| `404` na `git.intecion.net/.../ipal-kit.git` | nie zalogowany / brak tokenu w URL / brak uprawnień do repo | -| `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` | `prepare` w package.json (Droga B) — usuń, `dist` jest w repo | -| `Cannot find module .../src/...ts` | główny `exports` wskazuje src zamiast dist | -| stary kod mimo reinstall | cache; `pnpm store prune && rm -rf .next node_modules/@intecion` | +| `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` | -Więcej: [docs/install.md](./docs/install.md). \ No newline at end of file +If you get stuck, check **[docs/install.md](./docs/install.md)** or message the +team that maintains the plugin. \ No newline at end of file