159 lines
5.0 KiB
Markdown
159 lines
5.0 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.
|
|
|
|
```bash
|
|
# 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:**
|
|
|
|
```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
|
|
- **[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` 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](./docs/install.md)** or message the
|
|
team that maintains the plugin. |