131 lines
4.7 KiB
Markdown
131 lines
4.7 KiB
Markdown
# @intecion/ipal-kit
|
|
|
|
Intecion Payload Advanced Library — a plugin for Payload CMS 3.
|
|
|
|
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
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
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.
|
|
|
|
**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/
|
|
```
|
|
|
|
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:**
|
|
|
|
```bash
|
|
pnpm add @intecion/ipal-kit
|
|
```
|
|
|
|
That's it. No token, no login — the registry is public for reads.
|
|
|
|
### Why the registry, not a git install
|
|
|
|
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:
|
|
|
|
- **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.
|
|
|
|
Keep the git install only for pulling a specific unreleased commit during
|
|
plugin development.
|
|
|
|
---
|
|
|
|
## Finish setting up your project
|
|
|
|
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/[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.
|
|
|
|
---
|
|
|
|
## Publishing a new version
|
|
|
|
This section applies only if you develop the plugin itself. Publishing (unlike
|
|
installing) **does** need a token, with the `write:package` scope.
|
|
|
|
In `~/.npmrc` (path differs per OS — see the table below):
|
|
|
|
```
|
|
//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN}
|
|
```
|
|
|
|
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
|
|
npm version patch # 1.0.0 → 1.0.1
|
|
npm publish
|
|
```
|
|
|
|
Full checklist and troubleshooting: **[docs/publishing.md](./docs/publishing.md)**.
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
Everything lives in the **[docs/](./docs)** directory. To get started:
|
|
|
|
- **[getting-started.md](./docs/getting-started.md)** — project setup, step by step
|
|
- **[publishing.md](./docs/publishing.md)** — releasing new plugin versions
|
|
- **[README.md](./docs/README.md)** — index of the plugin's modules
|
|
|
|
---
|
|
|
|
## Something not working?
|
|
|
|
| What you see | What's wrong |
|
|
|---|---|
|
|
| `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, see **[docs/publishing.md](./docs/publishing.md)** or message the
|
|
team that maintains the plugin. |