# @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/plugin-seo@3.84.1 @payloadcms/plugin-form-builder@3.84.1 \
         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.