Update README.md
This commit is contained in:
@@ -1,160 +1,159 @@
|
|||||||
# @intecion/ipal-kit
|
# @intecion/ipal-kit
|
||||||
|
|
||||||
Intecion Payload Advanced Library — plugin do Payload CMS 3. Dostarcza i18n
|
Intecion Payload Advanced Library — a plugin for Payload CMS 3.
|
||||||
(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).
|
|
||||||
|
|
||||||
Repozytorium: https://git.intecion.net/IntecionSoftware/ipal-kit
|
Provides internationalization (per-locale routing, hreflang, language switcher),
|
||||||
(dostęp tylko dla zalogowanych pracowników Intecion).
|
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
|
The `git.intecion.net` server is internal — you'll only see the code and the
|
||||||
> po zalogowaniu. Każdy sposób instalacji wymaga tokenu dostępu (PAT) z konta
|
package once you're signed in to your Intecion account. Every installation method
|
||||||
> pracownika. Bez niego instalacja zwróci 404 albo błąd autoryzacji.
|
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:
|
### Generate a token
|
||||||
- `read:package` — do instalacji (wystarczy pracownikowi)
|
|
||||||
- `write:package` — dodatkowo, jeśli będziesz publikować wydania
|
|
||||||
|
|
||||||
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
|
Don't paste the token straight into project files. Keep it in an environment
|
||||||
i szybką instalację gotowego builda. **B (bezpośrednio z git)** nie wymaga
|
variable, so your install config carries no secret.
|
||||||
publikowania, ale buduje/pobiera z repo.
|
|
||||||
|
```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ą
|
There are two routes. Pick **Route A** if you just want to use the plugin in a
|
||||||
gotowy `dist` — bez budowania u siebie.
|
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/
|
@intecion:registry=https://git.intecion.net/api/packages/IntecionSoftware/npm/
|
||||||
//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN}
|
//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN}
|
||||||
```
|
```
|
||||||
|
|
||||||
Token w zmiennej środowiskowej (bezpieczniej niż wpisany wprost — `.npmrc` można
|
Because the token lives in the `${GITEA_TOKEN}` variable, this file holds no
|
||||||
wtedy nawet zacommitować):
|
secret — you can safely commit it.
|
||||||
|
|
||||||
```bash
|
**2. Install:**
|
||||||
# ~/.zshrc
|
|
||||||
export GITEA_TOKEN=twój_token_z_gitea
|
|
||||||
```
|
|
||||||
|
|
||||||
Instalacja:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pnpm add @intecion/ipal-kit
|
pnpm add @intecion/ipal-kit
|
||||||
```
|
```
|
||||||
|
|
||||||
### Publikacja (osoba wydająca)
|
### Route B — straight from the repository
|
||||||
|
|
||||||
W `package.json` pluginu (jest już ustawione):
|
pnpm clones the repository and uses the pre-built output. There's no `gitea:`
|
||||||
```json
|
shorthand — give the full address.
|
||||||
"publishConfig": {
|
|
||||||
"registry": "https://git.intecion.net/api/packages/IntecionSoftware/npm/"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`~/.npmrc` z tokenem `write:package`:
|
Over HTTPS with your token:
|
||||||
```
|
|
||||||
//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN}
|
|
||||||
```
|
|
||||||
|
|
||||||
Wydanie:
|
|
||||||
```bash
|
```bash
|
||||||
pnpm clean && pnpm build
|
pnpm add git+https://$GITEA_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git
|
||||||
npm version patch # 1.0.0 → 1.0.1
|
|
||||||
npm publish
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Zaleta rejestru: semver — pnpm zawsze widzi nową wersję, koniec z ręcznym
|
Or over SSH, if you have a key added in Gitea:
|
||||||
czyszczeniem cache. `publishConfig` działa poprawnie (exports z dist), nie musisz
|
|
||||||
ruszać głównego `exports`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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
|
```bash
|
||||||
pnpm add git+ssh://[email protected]:IntecionSoftware/ipal-kit.git
|
pnpm add git+ssh://[email protected]:IntecionSoftware/ipal-kit.git
|
||||||
```
|
```
|
||||||
|
|
||||||
**HTTPS z tokenem**:
|
Append a specific version after `#` to pin to a release:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pnpm add git+https://TWÓJ[email protected]/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Ó[email protected]/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
|
```bash
|
||||||
pnpm add @payloadcms/[email protected] @payloadcms/[email protected] \
|
pnpm add @payloadcms/[email protected] @payloadcms/[email protected] \
|
||||||
nodemailer lucide-react slugify server-only
|
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:
|
This section only applies if you develop the plugin itself and publish new
|
||||||
- [docs/getting-started.md](./docs/getting-started.md) — od zera do działającego projektu
|
versions. You'll need a token with the `write:package` scope.
|
||||||
- [docs/install.md](./docs/install.md) — szczegóły instalacji i diagnostyka
|
|
||||||
- [docs/README.md](./docs/README.md) — spis modułów
|
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` 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` na `git.intecion.net/.../ipal-kit.git` | nie zalogowany / brak tokenu w URL / brak uprawnień do repo |
|
| `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` | `prepare` w package.json (Droga B) — usuń, `dist` jest w repo |
|
| `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` | an attempt to build on install from git — report it to whoever publishes the plugin |
|
||||||
| `Cannot find module .../src/...ts` | główny `exports` wskazuje src zamiast dist |
|
| old code after reinstalling | cache: run `pnpm store prune`, then remove `.next` and `node_modules/@intecion` |
|
||||||
| stary kod mimo reinstall | cache; `pnpm store prune && rm -rf .next node_modules/@intecion` |
|
|
||||||
|
|
||||||
Więcej: [docs/install.md](./docs/install.md).
|
If you get stuck, check **[docs/install.md](./docs/install.md)** or message the
|
||||||
|
team that maintains the plugin.
|
||||||
Reference in New Issue
Block a user