Free & Open-Source Invoice Generator - No Sign-Up, No Ads, Instant PDF Export, 100% In-Browser, and Fully Customizable Templates.
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Project
EasyInvoicePDF — a free, browser-only invoice generator (Next.js App Router). Invoice data never leaves the browser: it lives in React state, is persisted to localStorage, and is rendered to PDF client-side with @react-pdf/renderer. The only server-side PDF path is the private /api/generate-invoice route the author uses for their own monthly invoice.
Package manager is pnpm (pinned via corepack). save-exact=true and a 5-day minimum-release-age are set in .npmrc, so add dependencies with exact versions.
Working agreements
Never commit and never stage. Do not run git commit, git add, or git stage — not even when the task is finished and every check is green. Leave the work in the working tree and report what changed; the user reviews and shapes their own commits. Committing also fires the heavy husky pre-commit hook, which rewrites files via oxfmt.
Follow the repo's own guidelines and skills. Before writing code, load what applies:
.cursor/rules/*.mdc— always-on coding, error-handling and testing conventions (summarized under Conventions, but read the source when in doubt)..cursor/skills/trigger-*— Trigger.dev playbooks (trigger-authoring-tasks,trigger-getting-started,trigger-authoring-chat-agent,trigger-cost-savings); required reading before touching anything insrc/trigger/ortrigger.config.ts..agents/skills/— task-scoped playbooks, vendored by theskills-lock.jsonsync tool. The ones that come up most here:vercel-react-best-practicesandvercel-composition-patterns(React/Next work),frontend-design,make-interfaces-feel-better,emil-design-engandweb-design-guidelines(UI),changelog-maintenance(changelog entries),writing-guidelines(docs and prose), theseo-*skills (landing pages and metadata).
Claude Code only discovers skills under .claude/skills/, so both directories are symlinked into it — that is what makes them invocable by name with the Skill tool. Re-run this after the sync tool adds a skill (idempotent; the CLI follows symlinked skill dirs):
mkdir -p .claude/skills && for src in .agents/skills .cursor/skills; do for d in "$src"/*/; do s=$(basename "$d"); [ -f "$d/SKILL.md" ] && ln -sfn "../../$src/$s" ".claude/skills/$s"; done; done
Commands
pnpm dev # next dev (Turbopack), port 3000, writes to .next/dev
pnpm build # next build (Turbopack); writes to .next, separate from .next/dev
pnpm type-check # next typegen + tsc --noEmit (TypeScript 7 native tsc)
pnpm type-check:fast # oxlint --type-check (faster, tsgolint)
pnpm lint # oxlint --type-aware (replaces eslint)
pnpm format # oxfmt (replaces prettier)
pnpm knip # unused files/exports/deps
pnpm vitest --run # unit tests, dir is ./src
pnpm e2e # Playwright, needs a server on BASE_URL (default localhost:3000)
Single tests:
pnpm vitest --run src/utils/__tests__/url-compression.test.ts -t "round trips"
pnpm e2e e2e/invoice-form.test.ts --project="Desktop Chrome" -g "adds an item"
Run as few e2e tests as possible. The full suite is slow (CI budgets 65 minutes across four browser projects) and most of that time is spent generating and rasterizing PDFs. Always narrow to the file you touched, and add --project="Desktop Chrome" plus -g "<test name>" on top of it. Run the whole suite only when a change is broad enough to warrant it, or when the user asks.
The pre-commit hook (lint-staged.config.js) runs type-check:fast, lint, zizmor, knip, vitest --run and format on any staged change, so keep all of those green.
Env vars come from .env.local, which may be encrypted with dotenvx (check for encrypted: values; the private key then lives in the OS keychain or a gitignored .env.keys). The dev, build, start, type-check and lint scripts decrypt it through pnpm with-env <cmd> (dotenvx run --strict, which stops on a decryption failure), so use those and never bare next ..., which would read the raw encrypted: strings. If the file is encrypted, change values with pnpm exec dotenvx set KEY value -f .env.local rather than editing it, then restart pnpm dev — Next's env hot-reload re-reads the encrypted file, so new keys arrive as ciphertext and changed ones stay stale until restart. Don't put NODE_ENV in it — dotenvx run would inject it into next dev/next start.
SKIP_ENV_VALIDATION=true is only for type-check/lint in CI — never set it for next dev or next build; next.config.mjs imports src/env.ts on purpose so a missing env var fails the build.
Architecture
Invoice data flow
src/app/schema/index.ts (~1450 lines) is the single source of truth: zod schemas plus every supported currency, language, date format and template, and the localStorage key constants. Everything downstream (form, PDF templates, share links, API route) derives its types from it.
src/app/(main)/(app)/page.client.tsxownsinvoiceDataState. On mount it hydrates from?data=(shared link) orlocalStorage, validating withinvoiceSchema.src/app/(main)/(app)/components/invoice-form/is areact-hook-formform resolved againstinvoiceSchema. Changes are debounced (DEBOUNCE_TIMEOUT = 500ms) before being pushed up and written tolocalStorage— e2e helpers wait on this debounce.InvoicePdfInstanceProvider(src/app/(main)/(app)/contexts/invoice-pdf-instance-context.tsx) renders the PDF once viausePDFand shares the blob/URL with the desktop preview, the mobile viewer and the download link. Do not add a secondusePDF/<PDFViewer>/<BlobProvider>on the page — react-pdf's module-level listener registry makes every instance re-render on any commit (flicker + duplicate work).- Sharing:
src/utils/url-compression.tsremaps long JSON keys to one-character keys, thenlz-stringencodes it into?data=. Adding a schema field means adding it toINVOICE_KEY_COMPRESSION_MAP(the map is type-checked against the schema keys).
Use zodResolverForOutput (src/lib/zod-resolver-for-output.ts) instead of zodResolver — form state is typed on the schema's output type.
PDF templates
Two templates under src/app/(main)/(app)/components/invoice-templates/: invoice-pdf-default-template/ and invoice-pdf-stripe-template/, selected by invoiceData.template. A change to one usually needs the mirrored change in the other, plus new snapshots.
- Always import from
@react-pdf/renderer/lib/react-pdf.browser, never@react-pdf/renderer(lint-enforced). - Fonts are self-hosted and registered per template via
INVOICE_PDF_FONTSinsrc/config.ts;srcmust stay an absolute URL. @react-pdf/rendererandreact-pdfversions are pinned deliberately — see the memory notes andpnpm-workspace.yamlbefore touching them.
fontkit patch (do not remove)
patches/[email protected] fixes dropped leading characters in generated PDFs ("Cobrar de" → "obrar de"). The version is baked into the patch filename, so bumping fontkit silently drops the fix. patches/README.md has the full root cause, and src/app/(main)/(app)/components/invoice-templates/__tests__/fontkit-glyph-cache-patch.test.ts fails if the patch is not actually applied to the resolved copy.
i18n — two separate systems
- UI/marketing copy:
next-intl, messages inmessages/*.json, locale-prefixed routes undersrc/app/[locale]/(src/proxy.ts, the Next 16proxyconvention, matches only those). The locale matcher is a static literal — keep it in sync withSUPPORTED_I18N_LOCALES(the languages the site is translated into, a subset ofSUPPORTED_INVOICE_PDF_LANGUAGES, which is the PDF's own list). - PDF content: a hand-rolled catalog,
src/app/(main)/(app)/pdf-i18n-translations/pdf-translations.ts, validated againstpdf-translations-schema.ts. Some entries are functions (e.g.vatAmount({ customTaxLabel })) so tax labels can be customized per invoice.
next.config.mjs validates both — every messages/*.json against src/app/schema/i18n-schema.ts and the PDF catalog against its schema — and process.exit(1)s on failure, so a missing translation key breaks dev and build.
Routing groups
There are two root layouts, both rendering the shared <html>/<body> shell from src/app/(components)/root-document.tsx (navigating between them is a full page load):
src/app/(main)/— root layout for the unprefixed, English-only routes.(app)/is the invoice generator itself, served at/;(seo-landings)/are data-driven landing pages (content inseo-landing-definitions.ts, pages built byseo-landing-route.tsx— add a slug toSEO_LANDING_SLUGSplus a directory, don't hand-write the page);changelog/renders MDX posts fromcontent/via@next/mdx; plusfounder/,how-it-works/,tos/andnot-found.tsx.src/app/[locale]/— root layout for the localized/aboutpage and catch-all. Because nothing sits above it,localeis a root param:src/i18n/request.tsreads it withnext/root-params, so components useuseLocale()/getLocale()and neversetRequestLocale()orparams.locale. Unknown locales fall back to the default inrequest.ts;about/layout.tsxturns them into a 404. The about page is prerendered per locale:generateStaticParamsin the[locale]layout plusdynamic = "force-static"inabout/layout.tsx, which is what lets the root document'sheaders()-based device detection run at build time (the same pattern as/changelog,/tos, ...).src/app/api/generate-invoice/— Bearer-token + Upstash rate-limited route that renders a PDF server-side, emails it (Resend) and uploads it to Google Drive. Scheduled by the Trigger.dev task insrc/trigger/monthly-recurring-invoice.ts.
Testing
- Unit tests (vitest) live in
__tests__/folders next to the code,dir: ./src. Node is the default environment; DOM tests opt in with a// @vitest-environment happy-domfirst line. - E2E (Playwright) is in
e2e/. There is nowebServer— startpnpm dev(or pointBASE_URLat a deployment) first. - PDF assertions download the file and rasterize it with
pdfjs-dist(e2e/utils/render-pdf-on-canvas.ts,e2e/utils/pdf-download.ts); snapshots are compared only on the Desktop Chrome project and were generated on macOS, which is why CI usesmacos-14. Timezone is forced toEurope/Warsaweverywhere. - Import
testfrome2e/utils/extended-playwright-test.ts(gives a per-testdownloadDirfixture); it must stay exported under the nametestfor the Playwright lint plugin. - If e2e is flaky locally, use
pnpm e2e:not-flaky(2 workers). - Prefer a unit test over an e2e test whenever the behaviour can be covered in
src/— e2e runs are expensive, see Commands.
Conventions
From .cursor/rules/ (all apply here):
- TypeScript everywhere; prefer interfaces over type aliases; no enums (
as constobjects); no classes;functionkeyword for pure functions. - Named exports for components; lowercase-dashed directory names; file order: exported component, subcomponents, helpers, static content, types.
- Prefer ternaries over
&&in JSX. Minimizeuse client,useEffect,setState— but note the app shell is inherently client-heavy because the PDF renders in the browser. - Model expected errors as return values, use guard clauses, zod for all validation.
console.logis lint-banned (console.error/info/warnallowed);process/node:processimports are banned — use@/env.- Reference material and known upstream bugs are collected in
KNOWLEDGE-BASE.md.
Beyond .cursor/rules/:
Take a single object argument, not positional ones. Any function with more than one parameter destructures an object:
// yes formatDateWithLocale({ date, selectedDateFormat, language }); // no formatDateWithLocale(date, selectedDateFormat, language);Call sites say what each value means without opening the signature, two same-typed parameters can't be swapped by accident, and adding a parameter doesn't touch every caller. Type the object as a named
interfaceabove the function and document each field with a doc comment on the property rather than@paramtags — seesrc/app/(main)/(app)/utils/format-date-with-locale.ts. One-parameter functions stay positional.