awl-npm-packages

Type	Skill
Plugin	awl-web · v0.0.6
Invoke	/awl-web:awl-npm-packages
Source	plugins/awl-web/skills/awl-npm-packages/SKILL.md

When Claude uses it

Catalogue and cheat sheets for AWL’s internal @awl/* npm packages (Svelte 5 headless components, SvelteKit helpers, Payload CMS plugins and client, Livingdocs client, utils, request, tailwindcss, Playwright matchers) plus registry setup. Use whenever a task touches an “@awl package”, asks “which awl package” fits, or names one of them (“svelte-form”, “svelte-select”, “svelte-overlay”, “svelte-query”, “svelte-switcher”, “svelte-toast”, “svelte-table”, “svelte-lexical”, “livingdocs client”, “awl utils”, “awl request”, “payload-api”, “payload-access-policies”), or when asked to “set up the awl registry” / “npm-packages storybook”. NOT for wiring a whole SvelteKit app (oidc, session, i18n, otel, request proxy) — use sveltekit-app-setup; NOT for installing Payload plugins end to end — use payload-plugins; NOT for writing tests — use awl-testing testing-web.

Trigger phrases: @awl package · which awl package · svelte-form · svelte-select · svelte-overlay · svelte-query · svelte-switcher · svelte-toast · svelte-table · svelte-lexical · livingdocs client · awl utils · awl request · payload-api · payload-access-policies · set up the awl registry · npm-packages storybook

Definition

AWL publishes reusable packages under the @awl scope from GitLab project 3919. The rendered docs live in a Storybook at https://npm-packages.staging.appswithlove.net. Every package has a condensed cheat sheet in references/, and each catalogue row links the live doc page. Snapshot of the doc index: plugins/awl-web/npm-packages-sources.json.

Registry setup

Point the @awl scope at the GitLab package registry once per machine, because the packages are private:

npm config set @awl:registry https://gitlab.appswithlove.net/api/v4/projects/3919/packages/npm/
npm config set //gitlab.appswithlove.net/api/v4/projects/3919/packages/npm/:_authToken YOUR_PERSONAL_ACCESS_TOKEN

Create the token at https://gitlab.appswithlove.net/-/user_settings/personal_access_tokens (name npm, scope api). In CI use CI_JOB_TOKEN and write an .npmrc in before_script; Docker builds mount that file as a build secret. See references/registry-setup.md for the CI and Dockerfile snippets and for publishing a package.

Most Svelte packages ship untransformed source, so add them to optimizeDeps.exclude in vite.config.ts. Payload packages are TypeScript-only, so list them in transpilePackages in next.config.js. The cheat sheets repeat the exact entries.

Catalogue

Svelte 5 (headless, unstyled)

Package	Purpose	Reach for it when	Peers	Docs
@awl/svelte-form	submitForm, inlineForm, queryForm factories, validations, InputField, SelectInput, FileInput, CoordinateInput	any client-side form: login, settings panel, filter bar, map picker	Svelte 5; leaflet optional	docs · references/svelte-form.md
@awl/svelte-overlay	dialog, popover, dropdown, sidebar, nested menu state and ARIA	you need a <dialog> or Popover API element with a trigger	Svelte 5	docs · references/svelte-overlay.md
@awl/svelte-select	single and multi select on top of svelte-overlay	a standalone select without form binding (inside forms prefer SelectInput from svelte-form)	Svelte 5	docs · references/svelte-select.md
@awl/svelte-query	reactive args → query fn → data, loading, error	live search or filter over async or in-memory data (overlaps with queryForm)	Svelte 5	docs · references/svelte-query.md
@awl/svelte-switcher	tabs, steppers, wizards, snap and endless carousels	anything with one current item out of many	Svelte 5	docs · references/svelte-switcher.md
@awl/svelte-collapsible	accessible collapsible and accordion	disclosure widgets following the APG accordion pattern	Svelte 5	docs · references/svelte-collapsible.md
@awl/svelte-toast	multi-stack toast provider rendering any component	notifications, confirm prompts, loading toasts	Svelte 5	docs · references/svelte-toast.md
@awl/svelte-table	snippet-based table with per-column cells	a data table styled with your own th/td/tr	Svelte 5	docs · references/svelte-table.md
@awl/svelte-lexical	headless Lexical rich-text editor, Payload-compatible links, placeholder tokens	rich text in a Svelte app that saves to a Payload richText field	Svelte 5, lexical	docs · references/svelte-lexical.md
@awl/svelte-attachments	intersect, nodeRegistry, align attachments	viewport observers, keyed DOM node lookup, anchoring floating elements	Svelte 5	docs · references/svelte-attachments.md
@awl/svelte-utils	ReactiveSearchParam	syncing state to a URL search param	Svelte 5	docs · references/svelte-utils.md
@awl/svelte	ReactiveCookie, Carousel	reactive document.cookie access	Svelte 5	docs · references/svelte.md
@awl/svelte-qrcode	SSR-safe <QRCode> SVG	rendering a QR code styled with CSS	Svelte 5	docs · references/svelte-qrcode.md
@awl/svelte-rive	rive() attachment and vmi() view-model helper	embedding a Rive animation on a <canvas>	Svelte 5, @rive-app/canvas	docs · references/svelte-rive.md

General and SvelteKit (app wiring lives in the sveltekit-app-setup skill)

Package	Purpose	Reach for it when	Peers	Docs
@awl/oidc	OIDC via oauth4webapi with SvelteKit and Payload adapters	login, token refresh, route guards; needs @awl/session on SvelteKit	SvelteKit or Payload	docs · references/oidc.md
@awl/session	session with Memory, Cookie, FileSystem, Redis storage	server-side session on event.locals.session or req.session	SvelteKit or Payload	docs · references/session.md
@awl/i18n	typed pluggable i18n, SvelteKit hook, Payload adapter, preprocessor, extractor	translations shared between SvelteKit and Payload	Svelte 5 for /svelte and /vite	docs · references/i18n.md
@awl/opentelemetry	typed metrics with OTLP or Prometheus readers	counters and gauges in a Node backend	@opentelemetry/exporter-* peers	docs · references/opentelemetry.md
@awl/sveltekit-oidc	older cookie-based OIDC for SvelteKit with only guards	a project already on it; new setups follow the @awl/oidc docs	SvelteKit	docs · references/sveltekit-oidc.md
@awl/sveltekit-utils	only(handle).path().method().when()	scoping a Handle to routes, methods, headers	SvelteKit	docs · references/sveltekit-utils.md

Payload CMS (plugin installation lives in the payload-plugins skill)

Package	Purpose	Reach for it when	Peers	Docs
@awl/payload-api	pluggable REST client, SvelteKit proxy, Svelte form plugin, Image media component	a frontend talks to Payload	Svelte 5 for /svelte and /media	docs · references/payload-api.md
@awl/payload-access-policies	or, and, ownerOnly, createAccessMatrix	composing collection or field access	Payload v3	docs · references/payload-access-policies.md
@awl/payload-features	context-driven feature flags with admin rules collection	flags per request, feature-gated access	Payload v3	docs · references/payload-features.md
@awl/payload-oidc	OIDC plugin with bearer strategy and user upsert	external IdP for the Payload admin (see also @awl/oidc/payload)	Payload	docs · references/payload-oidc.md
@awl/payload-change-requests	per-field change requests instead of drafts	proposing gated field edits for approval	Payload v3	docs · references/payload-change-requests.md
@awl/payload-dynamic-refs	named references resolved at runtime	code needs a document an editor wires up later	Payload	docs · references/payload-dynamic-refs.md
@awl/payload-email-templates	render() Lexical content to email HTML with placeholders	sending admin-authored emails	Payload, @awl/lexical-placeholder	docs (page broken, see cheat sheet) · references/payload-email-templates.md
@awl/lexical-placeholder	shared PlaceholderNode for {dot.path} tokens	building a third editor integration	lexical	docs · references/lexical-placeholder.md

Livingdocs, testing, utilities

Package	Purpose	Reach for it when	Peers	Docs
@awl/livingdocs-client	LivingdocsClient class, /functions, /with-env	reading publications, menus, media from Livingdocs	—	docs · references/livingdocs-client.md
@awl/livingdocs-types	publication, component, native types (Swiss gov instances)	typing Livingdocs responses	—	docs · references/livingdocs-types.md
@awl/playwright-a11y	toBeAccessible() axe matcher	e2e accessibility checks (test strategy: awl-testing testing-web)	@playwright/test	docs · references/playwright-a11y.md
@awl/playwright-sveltekit	toBeHydrated() matcher	waiting for SvelteKit hydration in e2e tests	@playwright/test	docs · references/playwright-sveltekit.md
@awl/utils	safe, debounce, delay, base64, cookies, crypto, dot, pluggable, createProxy, searchparams, html, errors, compression	small framework-free helpers	—	docs · references/utils.md
@awl/request	pluggable fetch builder: vars, path, options, auth, jsonApi	a typed HTTP client without a framework	—	docs · references/request.md
@awl/tailwindcss	px-based Tailwind theme with device breakpoints	every AWL Tailwind project	Tailwind v4	docs · references/tailwindcss.md

How to use this catalogue

1. Pick the package from the table. When two overlap (svelte-query and queryForm, svelte-select and SelectInput, @awl/oidc and @awl/sveltekit-oidc), prefer what the project already depends on, then the one whose docs are more complete.

2. Read references/<package>.md before writing code. The cheat sheets copy signatures and option tables from the docs, so they are the source for API names.

3. When the cheat sheet does not answer the question, fetch the live page instead of guessing an API. The Storybook renders client-side, so a plain fetch returns an empty shell:

   firecrawl scrape "https://npm-packages.staging.appswithlove.net/?path=/docs/<id>" --format markdown --wait-for 2500

   <id> is the doc id from the catalogue link (for example svelte-svelte-form--readme). The iframe URL https://npm-packages.staging.appswithlove.net/iframe.html?viewMode=docs&id=<id> renders the same page without the sidebar.

4. Add the Vite optimizeDeps.exclude or Next.js transpilePackages entry the cheat sheet lists, because missing it fails at runtime rather than at build time.

5. If the docs lack something (several pages carry TODOs), say so and link the page rather than inventing a method.

Known doc gaps

• The Storybook overview pages link to --docs ids that do not exist; the real pages end in --readme (or --only, --docs for request). The Svelte overview also omits half the Svelte packages.
• payload-payload-email-templates--readme throws user is not defined when rendered. The cheat sheet was recovered from the compiled MDX asset.
• livingdocs-livingdocs-client--functions lists no function signatures (TODO in the doc). Use the client class page and the OpenAPI spec it links.
• svelte-ui-rive--readme tells you to exclude @awl/svelte-overlay from Vite optimizeDeps; that is a copy-paste error, exclude @awl/svelte-rive.