IntecionSoftware/ipal-kit
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated docs

Browse Source
This commit is contained in:
radoslaw.smolinski
2026-08-12 17:54:40 +02:00
parent 4eedc1f642
commit 195d4169f5
7 changed files with 287 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+48 -116
View File
@@ -11,99 +11,23 @@ blog/archive system (collections under an archive page, listing, pagination).
---
## 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.
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.
### 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:
**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/
//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).
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:**
@@ -111,28 +35,25 @@ secret — you can safely commit a project-level `.npmrc`.
pnpm add @intecion/ipal-kit
```
### Route B — straight from the repository
That's it. No token, no login — the registry is public for reads.
pnpm clones the repository and uses the pre-built output. There's no `gitea:`
shorthand — give the full address.
### Why the registry, not a git install
Over HTTPS with your token:
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:
```bash
pnpm add git+https://$GITEA_TOKEN@git.intecion.net/IntecionSoftware/ipal-kit.git
```
- **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.
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
```
Keep the git install only for pulling a specific unreleased commit during
plugin development.
---
@@ -146,6 +67,10 @@ 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.
@@ -153,16 +78,25 @@ 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.
This section applies only if you develop the plugin itself. Publishing (unlike
installing) **does** need a token, with the `write:package` scope.
In `~/.npmrc`:
In `~/.npmrc` (path differs per OS — see the table below):
```
//git.intecion.net/api/packages/IntecionSoftware/npm/:_authToken=${GITEA_TOKEN}
```
Build, bump the version number, publish:
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
@@ -170,8 +104,7 @@ 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.
Full checklist and troubleshooting: **[docs/publishing.md](./docs/publishing.md)**.
---
@@ -189,11 +122,10 @@ Everything lives in the **[docs/](./docs)** directory. To get started:
| 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` |
| `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, check the troubleshooting table above, see
**[docs/publishing.md](./docs/publishing.md)** for distribution issues, or message
the team that maintains the plugin.
If you get stuck, see **[docs/publishing.md](./docs/publishing.md)** or message the
team that maintains the plugin.