ipal-kit/README.md

@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

---

Before you start

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.

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.

Generate a token

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.

Store the token in your environment

Don't paste the token straight into project files. Keep it in an environment variable, so your install config carries no secret.

# add to ~/.zshrc (or ~/.bashrc)
export GITEA_TOKEN=paste_your_token_here

Reload your shell (source ~/.zshrc) or open a new terminal window.

---

Installation

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.

Route A — from the registry (recommended)

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}

Because the token lives in the ${GITEA_TOKEN} variable, this file holds no secret — you can safely commit it.

2. Install:

pnpm add @intecion/ipal-kit

Route B — straight from the repository

pnpm clones the repository and uses the pre-built output. There's no gitea: shorthand — give the full address.

Over HTTPS with your token:

pnpm add git+https://$GITEA_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git

Or over SSH, if you have a key added in Gitea:

pnpm add git+ssh://[email protected]:IntecionSoftware/ipal-kit.git

Append a specific version after # to pin to a release:

pnpm add git+https://$GITEA_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git#v1.0.0

---

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:

pnpm add @payloadcms/[email protected] @payloadcms/[email protected] \
         nodemailer lucide-react slugify server-only

From here, the guide takes over: docs/getting-started.md — from an empty project to a working site.

---

Publishing a new version

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:

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.

---

Documentation

Everything lives in the docs/ directory. To get started:

• getting-started.md — project setup, step by step
• install.md — more on installation and troubleshooting
• README.md — index of the plugin's modules

---

Something not working?

What you see	What's wrong
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

If you get stuck, check docs/install.md or message the team that maintains the plugin.