199 lines
6.5 KiB
Markdown
199 lines
6.5 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
|
|
|
|
---
|
|
|
|
## 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. How you set it depends on
|
|
your system:
|
|
|
|
**macOS** (default shell is zsh):
|
|
```bash
|
|
echo 'export GITEA_TOKEN=paste_your_token_here' >> ~/.zshrc
|
|
source ~/.zshrc
|
|
```
|
|
|
|
**Linux / Ubuntu** (default shell is bash):
|
|
```bash
|
|
echo 'export GITEA_TOKEN=paste_your_token_here' >> ~/.bashrc
|
|
source ~/.bashrc
|
|
```
|
|
|
|
**Windows (PowerShell)** — set it permanently for your user, then open a new
|
|
terminal so it takes effect:
|
|
```powershell
|
|
setx GITEA_TOKEN "paste_your_token_here"
|
|
```
|
|
|
|
> On Windows, `setx` writes the variable but does **not** affect the current
|
|
> window — close it and open a new PowerShell for the token to be visible.
|
|
|
|
---
|
|
|
|
## 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.** Add these two lines to an `.npmrc` file:
|
|
|
|
```
|
|
@intecion:registry=https://git.intecion.net/api/packages/IntecionSoftware/npm/
|
|
//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN}
|
|
```
|
|
|
|
You can put this file **in the project directory** (applies to that project) or
|
|
**globally** (applies everywhere). The global location differs by system:
|
|
|
|
| System | Global `.npmrc` path |
|
|
|---|---|
|
|
| macOS | `~/.npmrc` (i.e. `/Users/you/.npmrc`) |
|
|
| Linux / Ubuntu | `~/.npmrc` (i.e. `/home/you/.npmrc`) |
|
|
| Windows | `%USERPROFILE%\.npmrc` (i.e. `C:\Users\you\.npmrc`) |
|
|
|
|
Fastest way to create the global file:
|
|
|
|
```bash
|
|
# macOS / Linux
|
|
npm config set @intecion:registry https://git.intecion.net/api/packages/IntecionSoftware/npm/
|
|
```
|
|
```powershell
|
|
# Windows (PowerShell) — same command, npm handles the path
|
|
npm config set @intecion:registry https://git.intecion.net/api/packages/IntecionSoftware/npm/
|
|
```
|
|
|
|
Then add the auth line manually (npm config doesn't set tokens with variables).
|
|
Because the token lives in the `${GITEA_TOKEN}` variable, the file holds no
|
|
secret — you can safely commit a project-level `.npmrc`.
|
|
|
|
> **Windows note:** the `${GITEA_TOKEN}` syntax in `.npmrc` is expanded by npm/pnpm
|
|
> itself, not by the shell — so it works the same on Windows as on macOS/Linux,
|
|
> as long as you set the variable with `setx` (see above).
|
|
|
|
**2. Install:**
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
pnpm add git+https://$GITEA_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git
|
|
```
|
|
|
|
Or over SSH, if you have a key added in Gitea:
|
|
|
|
```bash
|
|
pnpm add git+ssh://[email protected]:IntecionSoftware/ipal-kit.git
|
|
```
|
|
|
|
Append a specific version after `#` to pin to a release:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
pnpm add @payloadcms/[email protected] @payloadcms/[email protected] \
|
|
nodemailer lucide-react slugify server-only
|
|
```
|
|
|
|
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 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.
|
|
|
|
---
|
|
|
|
## 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` 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 the troubleshooting table above, see
|
|
**[docs/publishing.md](./docs/publishing.md)** for distribution issues, or message
|
|
the team that maintains the plugin. |