Website

This page describes how to develop writewithharper.com locally. If you are comfortable with JavaScript or TypeScript but new to Svelte, start with Prerequisites and Running the Site , then skim Where Code Lives .

Make sure you read the introduction to contributing and committing guides before opening a pull request.

Notes

Prerequisites

  • Set up your environment . For website-only work you need node, pnpm, and just in your $PATH. You do not need a full Rust toolchain unless you are changing harper-wasm or harper-core.
  • From the repository root, run just setup once (or at least just build-web) so workspace dependencies and WASM artifacts are built.
  • Node 22+ and pnpm 10 match what Harper uses in CI (see the root package.json engines field).

Where Code Lives

PathPurpose
packages/web/src/routes/Site routes: marketing pages (.svelte), docs (.md), and API handlers (+server.ts)
packages/web/src/routes/docs/Contributor and user documentation (this page is contributors/website/+page.md)
packages/web/src/lib/Shared Svelte components, marketing sections, and small utilities
packages/web/vite.config.tsVite config, SveltePress theme, and documentation sidebar
packages/lint-framework/Browser linting UI (underlines, popups) reused by the site and extensions
packages/harper-editor/Embeddable Harper editor used on the homepage and /editor
packages/components/Shared UI primitives consumed by the site and other packages
packages/harper.js/JavaScript API over harper-wasm

Documentation sidebar entries are defined in packages/web/vite.config.ts. When you add a new doc page, register it there so it appears in the left nav.

Running the Site

The recommended way to start a dev server:

just dev-web
bash

This builds harper.js, lint-framework, components, and harper-editor, then runs pnpm dev in packages/web.

Open http://localhost:3000 . Vite hot-reloads most edits to .svelte, .ts, and .md files automatically.

just build-web only produces a production build; it does not start a dev server. Use just dev-web when you want to preview changes interactively.

If You Change Lower-Level Packages

  • Edits under packages/web usually reload without restarting.
  • If you change packages/components, packages/harper-editor, or packages/lint-framework, rebuild that package (or re-run just dev-web).
  • If you change harper-wasm / harper-core, re-run just dev-web (or just build-harperjs) so the site picks up a new WASM build.

Manual Alternative

From the repo root:

just build-harperjs build-lint-framework build-components build-harper-editor
cd packages/web
pnpm install
pnpm dev
bash

Previewing Your Changes

What you changedWhere to look
A documentation pagehttp://localhost:3000/docs/... (path mirrors src/routes/docs/...)
Homepage or marketing UIhttp://localhost:3000/
Live grammar demo / editorhttp://localhost:3000/ (demo) or http://localhost:3000/editor
Rule cataloghttp://localhost:3000/docs/rules
Weir studiohttp://localhost:3000/weir/studio

SveltePress doc pages support standard Markdown plus SveltePress features (admonitions, embedded code, etc.). Use an existing page under src/routes/docs/ as a template.

Each doc page has an Edit this page link (configured in vite.config.ts) that opens the matching file on GitHub.

Svelte and SvelteKit (For JS/TS Developers)

You do not need deep Svelte expertise for many contributions.

  • Routes: Files in src/routes/ map to URLs. +page.svelte is a page component; +page.md is a SveltePress doc page; +server.ts is a server endpoint.
  • Components: Reusable UI lives in src/lib/. Import with $lib/... (SvelteKit alias).
  • Scripts: <script lang="ts"> holds component logic. Harper uses Svelte 5 (runes like $state appear in newer components).
  • Styles: Tailwind CSS v4 is enabled via @tailwindcss/vite in vite.config.ts. Component-scoped <style> blocks are also used.

Official references: Svelte tutorial , SvelteKit docs .

Testing and Validation

Before opening a pull request:

just format
just precommit
bash

For website-focused checks:

cd packages/web
pnpm check
bash

pnpm check runs svelte-check (TypeScript and Svelte diagnostics). The root just check recipe also runs pnpm check for the whole workspace and includes just build-web.

There is no dedicated website unit-test package today; rely on pnpm check, a manual click-through in the browser, and CI.

Production Build Smoke Test

just build-web
cd packages/web
pnpm preview
bash

Then open the URL printed by vite preview (defaults differ from dev; confirm in the terminal output).

Docker (Optional)

Reviewers sometimes test grammar changes via the site demo using Docker ( see also the review guide ):

docker build . -q
docker run -p 3000:3000 -it <image-id>
bash

You do not need Docker for everyday website UI or documentation work.

Server Features (Usually Optional)

A few routes persist data with MariaDB via Drizzle ORM (for example uninstall feedback and problematic-lint reports). Local API work is optional:

  1. Start a database: docker compose -f docker-compose.dev.yml up from the repo root.
  2. Set DATABASE_URL for packages/web (see packages/web/drizzle.config.ts).
  3. Run migrations on app start (src/hooks.server.ts).

Most contributors never need this to change docs, marketing pages, or the public demo.

Deployment

Merges to master trigger the Build Web workflow, which builds the root Dockerfile and publishes the site image. You do not need to deploy manually to test a pull request; maintainers handle production releases.

Related Reading

Suggest changes to this page
Last update at: Invalid Date
An
Grammar Checker