Skip to content
Apps with loveApps with loveAWL Claude Code

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

Section titled “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

Section titled “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

Section titled “Registry setup”

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

Terminal window
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

Section titled “Catalogue”

Svelte 5 (headless, unstyled)

Section titled “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)

Section titled “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)

Section titled “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

Section titled “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

Section titled “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:

    Terminal window
    firecrawl scrape "https://npm-packages.staging.appswithlove.net/?path=/docs/&lt;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

Section titled “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.