Offline, privacy-first grammar checker. Fast, open-source, Rust-powered
feat(web): produce graphs and tables for reports (#3858)
Elijah Potterdf6d660013d8
diff --git a/Dockerfile b/Dockerfileindex 8b2148b89..c863520c5 100644--- a/Dockerfile+++ b/Dockerfile@@ -47,6 +47,7 @@ WORKDIR /usr/build/packages/harper-editorRUN pnpm buildWORKDIR /usr/build/packages/web+ENV ENABLE_ADMIN_ROUTES=falseRUN pnpm install --engine-strict=false --shamefully-hoistRUN pnpm builddiff --git a/justfile b/justfileindex 66c6bbc9a..2a52b59df 100644--- a/justfile+++ b/justfile@@ -162,7 +162,7 @@ build-web: build-harperjs build-lint-framework build-components build-harper-edicd "{{justfile_directory()}}/packages/web"pnpm install- pnpm build+ ENABLE_ADMIN_ROUTES=false pnpm build# Start a development server for Harper Desktop.dev-desktop: build-harperjs build-lint-framework build-components build-harper-editor@@ -444,9 +444,9 @@ check-rust: audit-dictionarycargo hack check --each-feature# Perform format and type checking.-check: check-rust check-js build-web+check: check-rust check-js-check-js: build-harperjs build-lint-framework build-components build-harper-editor+check-js: build-harperjs build-lint-framework build-components build-harper-editor build-web#!/usr/bin/env bashset -eo pipefail@@ -455,7 +455,7 @@ check-js: build-harperjs build-lint-framework build-components build-harper-edit# Needed because Svelte has special linterscd "{{justfile_directory()}}/packages/web"- pnpm check+ ENABLE_ADMIN_ROUTES=false pnpm check# Populate build caches and install necessary local tooling (tools callable via `pnpm run <tool>`).setup: build-harperjs test-harperjs test-vscode build-web build-wp build-obsidian build-chrome-plugindiff --git a/packages/components/src/lib/GutterCenter.svelte b/packages/components/src/lib/GutterCenter.svelteindex eb3eb7ea5..7c352a26d 100644--- a/packages/components/src/lib/GutterCenter.svelte+++ b/packages/components/src/lib/GutterCenter.svelte@@ -1,5 +1,5 @@<div class="flex flex-row justify-center h-full">- <div class="lg:w-[1024px] w-full h-full">+ <div class="w-full h-full max-w-5xl"><slot /></div></div>diff --git a/packages/components/src/lib/Isolate.svelte b/packages/components/src/lib/Isolate.svelteindex 0b9ad980b..f66557f32 100644--- a/packages/components/src/lib/Isolate.svelte+++ b/packages/components/src/lib/Isolate.svelte@@ -1,3 +1,3 @@-<div class="fixed left-0 top-0 w-screen h-screen bg-white dark:bg-black z-1000">+<div class="fixed left-0 top-0 w-screen h-screen bg-white dark:bg-black z-1000 overflow-auto"><slot /></div>diff --git a/packages/components/src/lib/styles.css b/packages/components/src/lib/styles.cssindex 0b35f5a97..84b392bc9 100644--- a/packages/components/src/lib/styles.css+++ b/packages/components/src/lib/styles.css@@ -8,6 +8,8 @@@source "./node_modules/flowbite-svelte/**/*.{svelte,ts,js}";@theme {+ --font-serif: Domine, serif;+--color-primary-50: #fef4e7; /* honey bronze */--color-primary-100: #fce9cf;--color-primary-200: #f9d49f;diff --git a/packages/harper-editor/src/lib/styles.css b/packages/harper-editor/src/lib/styles.cssindex ebf498bb9..abc97afd5 100644--- a/packages/harper-editor/src/lib/styles.css+++ b/packages/harper-editor/src/lib/styles.css@@ -4,6 +4,10 @@@source "./**/*.{svelte,ts}";+@theme {+ --font-serif: Domine, serif;+}+.harper-editor {--harper-editor-font-size: inherit;}diff --git a/packages/web/src/hooks.server.ts b/packages/web/src/hooks.server.tsindex 206d2da48..978590587 100644--- a/packages/web/src/hooks.server.ts+++ b/packages/web/src/hooks.server.ts@@ -1,10 +1,22 @@+import { error, type Handle } from '@sveltejs/kit';import { migrate } from 'drizzle-orm/mysql2/migrator';+import { ENABLE_ADMIN_ROUTES } from '$env/static/private';import { db } from '$lib/db';-// Migrate exactly once at startup+// Migrate the database exactly once at startuptry {await migrate(db, { migrationsFolder: './drizzle', migrationsTable: '__drizzle_migrations' });} catch (e: any) {console.log('Failed to migrate database.');console.error(e);}++export const handle: Handle = async ({ event, resolve }) => {+ const adminRoutesEnabled = ENABLE_ADMIN_ROUTES === 'true';++ if (!adminRoutesEnabled && event.route.id?.startsWith('/admin')) {+ error(404, 'Not found');+ }++ return resolve(event);+};diff --git a/packages/web/src/lib/components/AnalyticsPage.svelte b/packages/web/src/lib/components/AnalyticsPage.sveltenew file mode 100644index 000000000..a07c5d57c--- /dev/null+++ b/packages/web/src/lib/components/AnalyticsPage.svelte@@ -0,0 +1,46 @@+<script lang="ts">+import { GutterCenter, Isolate } from 'components';+import BarChart from './BarChart.svelte';++type Props = {+ data: Record<string, number>;+ title: string;+ links: Record<string, string>;+};++let { data, title, links }: Props = $props();++let counts = $derived(data);+let entries = $derived(Object.entries(counts).toSorted(([_a, a], [_b, b]) => b - a));+</script>++<Isolate>+ <h1>{title}</h1>++ <div class="flex flex-row [&>a]:px-4">+ {#each Object.entries(links) as [name, href]}+ <a href={href}>{name}</a>+ {/each}+ </div>++ <GutterCenter >+ <BarChart data={counts} title="Most Commonly Complained-About Lint IDs"/>++ <table>+ <thead>+ <tr>+ <th>Lint ID</th>+ <th>Value</th>+ </tr>+ </thead>+ <tbody>+ {#each entries as [key, value] }+ <tr>+ <th scope="row">{key}</th>+ <td>{value}</td>+ </tr>+ {/each}+ </tbody>+ </table>+ </GutterCenter>+</Isolate>diff --git a/packages/web/src/lib/components/BarChart.svelte b/packages/web/src/lib/components/BarChart.sveltenew file mode 100644index 000000000..2352dcc94--- /dev/null+++ b/packages/web/src/lib/components/BarChart.svelte@@ -0,0 +1,121 @@+<script lang="ts">+import Chart from 'chart.js/auto';+import { onMount } from 'svelte';++interface Props {+ data?: Record<string, number>;+ title: string;+}++let { data = {}, title }: Props = $props();++let chartCanvas = $state<HTMLCanvasElement>();+let chart: Chart | null = null;++let sortedEntries = $derived(Object.entries(data).toSorted(([_a, a], [_b, b]) => b - a));+let keys = $derived(sortedEntries.map(([a]) => a));+let values = $derived(sortedEntries.map(([, b]) => b));++onMount(() => {+ // Create a new Chart.js bar chart on mount+ chart = new Chart(chartCanvas!, {+ type: 'bar',+ data: {+ labels: keys,+ datasets: [+ {+ data: values,+ borderColor: 'rgba(80, 80, 80, 1)',+ borderWidth: 2,+ borderRadius: 6, // Rounded corners+ barPercentage: 0.6, // Thicker bars+ },+ ],+ },+ options: {+ responsive: true,+ maintainAspectRatio: false,+ plugins: {+ title: {+ display: true,+ text: title,+ color: '#444', // Dark gray text+ font: {+ size: 18,+ weight: 'bold',+ },+ },+ legend: {+ display: false,+ },+ },+ scales: {+ x: {+ grid: {+ color: '#ddd',+ },+ ticks: {+ color: '#333',+ font: {+ size: 14,+ },+ },+ },+ y: {+ beginAtZero: true,+ grid: {+ color: '#ddd',+ },+ ticks: {+ stepSize: 1,+ color: '#333',+ font: {+ size: 14,+ },+ },+ },+ },+ },+ });+});++// Update the chart data with new lint counts+function updateChart() {+ if (chart) {+ chart.data.labels = keys;+ chart.data.datasets[0].data = values;+ chart.update();+ }+}++// Whenever data changes, update the chart+$effect(() => {+ if (data) {+ updateChart();+ }+});+</script>+++<style>+ /* Wrap the chart in a container to control layout and background */+ .chart-container {+ background: #f9f9f9; /* Subtle off-white background */+ border: 1px solid #ccc; /* Light gray border */+ border-radius: 8px; /* Rounded corners */+ padding: 1rem;+ width: 100%;+ max-width: 700px; /* Adjust as needed */+ height: 400px; /* Fixed height for the chart area */+ margin: 0 auto; /* Center horizontally */+ }++ canvas {+ width: 100%;+ height: 100%;+ }+</style>++<div class="chart-container">+ <canvas bind:this={chartCanvas}></canvas>+</div>diff --git a/packages/web/src/lib/components/LintKindChart.svelte b/packages/web/src/lib/components/LintKindChart.svelteindex 008b44cf5..19779b3a0 100644--- a/packages/web/src/lib/components/LintKindChart.svelte+++ b/packages/web/src/lib/components/LintKindChart.svelte@@ -1,113 +1,9 @@<script lang="ts">-import Chart from 'chart.js/auto';-import { lintKindColor } from 'lint-framework';-import { onMount } from 'svelte';+import BarChart from './BarChart.svelte';// Receive lint counts from the parent componentexport let lintCounts: Record<string, number> = {};--let chartCanvas: HTMLCanvasElement;-let lintChart: Chart | null = null;--// Update the chart data with new lint counts-function updateChart() {- if (lintChart) {- lintChart.data.labels = Object.keys(lintCounts);- lintChart.data.datasets[0].data = Object.values(lintCounts);- lintChart.update();- }-}--onMount(() => {- // Create a new Chart.js bar chart on mount- lintChart = new Chart(chartCanvas, {- type: 'bar',- data: {- labels: Object.keys(lintCounts),- datasets: [- {- label: 'Number of Corrections Applied',- data: Object.values(lintCounts),- backgroundColor: Object.keys(lintCounts).map(lintKindColor),- borderColor: 'rgba(80, 80, 80, 1)',- borderWidth: 2,- borderRadius: 6, // Rounded corners- barPercentage: 0.6, // Thicker bars- },- ],- },- options: {- responsive: true,- maintainAspectRatio: false,- plugins: {- title: {- display: true,- text: 'Most Common Kinds of Corrections',- color: '#444', // Dark gray text- font: {- size: 18,- weight: 'bold',- },- },- legend: {- display: false,- },- },- scales: {- x: {- grid: {- color: '#ddd',- },- ticks: {- color: '#333',- font: {- size: 14,- },- },- },- y: {- beginAtZero: true,- grid: {- color: '#ddd',- },- ticks: {- stepSize: 1,- color: '#333',- font: {- size: 14,- },- },- },- },- },- });-});--// Whenever lintCounts changes, update the chart-$: if (lintChart) {- updateChart();-}</script>-<style>- /* Wrap the chart in a container to control layout and background */- .chart-container {- background: #f9f9f9; /* Subtle off-white background */- border: 1px solid #ccc; /* Light gray border */- border-radius: 8px; /* Rounded corners */- padding: 1rem;- width: 100%;- max-width: 700px; /* Adjust as needed */- height: 400px; /* Fixed height for the chart area */- margin: 0 auto; /* Center horizontally */- }-- canvas {- width: 100%;- height: 100%;- }-</style>+<BarChart data={lintCounts} title="Most Common Kinds of Corrections" />-<div class="chart-container">- <canvas bind:this={chartCanvas}></canvas>-</div>diff --git a/packages/web/src/lib/db/models/ProblematicLints.ts b/packages/web/src/lib/db/models/ProblematicLints.tsindex c95c08e13..b7e6a4f81 100644--- a/packages/web/src/lib/db/models/ProblematicLints.ts+++ b/packages/web/src/lib/db/models/ProblematicLints.ts@@ -1,3 +1,4 @@+import { gte } from 'drizzle-orm';import { createInsertSchema, createSelectSchema } from 'drizzle-zod';import { db } from '..';import { problematicLintTable } from '../schema';@@ -17,4 +18,15 @@ export default class ProblematicLints {public static async create(rec: ProblematicLintSubmission) {await db.insert(problematicLintTable).values(rec);}++ public static async getAll(): Promise<ProblematicLintRow[]> {+ return await db.select().from(problematicLintTable);+ }++ public static async getAllSince(date: Date) {+ return await db+ .select()+ .from(problematicLintTable)+ .where(gte(problematicLintTable.timestamp, date));+ }}diff --git a/packages/web/src/lib/db/models/UninstallFeedback.ts b/packages/web/src/lib/db/models/UninstallFeedback.tsindex b0147c3ef..b7bcdbb4a 100644--- a/packages/web/src/lib/db/models/UninstallFeedback.ts+++ b/packages/web/src/lib/db/models/UninstallFeedback.ts@@ -1,3 +1,4 @@+import { gte } from 'drizzle-orm';import { createInsertSchema, createSelectSchema } from 'drizzle-zod';import { db } from '..';import { uninstallFeedbackTable } from '../schema';@@ -17,4 +18,11 @@ export default class UninstallFeedback {public static async create(rec: UninstallFeedbackSubmission) {await db.insert(uninstallFeedbackTable).values(rec);}++ public static async getAllSince(date: Date) {+ return await db+ .select()+ .from(uninstallFeedbackTable)+ .where(gte(uninstallFeedbackTable.timestamp, date));+ }}diff --git a/packages/web/src/routes/admin/ext-uninstall-reasons/[slug]/+page.server.ts b/packages/web/src/routes/admin/ext-uninstall-reasons/[slug]/+page.server.tsnew file mode 100644index 000000000..39747eed3--- /dev/null+++ b/packages/web/src/routes/admin/ext-uninstall-reasons/[slug]/+page.server.ts@@ -0,0 +1,42 @@+import { redirect } from '@sveltejs/kit';+import UninstallFeedback from '$lib/db/models/UninstallFeedback';++export const load = async ({ params }) => {+ const slug = params.slug;++ let date = null;++ switch (slug) {+ case 'last30days':+ date = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);+ break;+ case 'lastday':+ date = new Date(Date.now() - 24 * 60 * 60 * 1000);+ break;+ case 'all':+ date = new Date(0);+ break;+ }++ if (date == null) {+ redirect(302, '/admin/ext-uninstall-reasons/all');+ }++ const problematicLints = await UninstallFeedback.getAllSince(date);++ const counts: Record<string, number> = {};++ for (const item of problematicLints) {+ const id = item.feedback ?? 'OTHER';++ if (counts[id] === undefined) {+ counts[id] = 1;+ } else {+ counts[id] += 1;+ }+ }++ return {+ counts,+ };+};diff --git a/packages/web/src/routes/admin/ext-uninstall-reasons/[slug]/+page.svelte b/packages/web/src/routes/admin/ext-uninstall-reasons/[slug]/+page.sveltenew file mode 100644index 000000000..9575991d9--- /dev/null+++ b/packages/web/src/routes/admin/ext-uninstall-reasons/[slug]/+page.svelte@@ -0,0 +1,13 @@+<script lang="ts">+import AnalyticsPage from '$lib/components/AnalyticsPage.svelte';+import type { PageProps } from './$types';++let { data }: PageProps = $props();+let links = {+ All: '/admin/ext-uninstall-reasons/all',+ 'Last 30 Days': '/admin/ext-uninstall-reasons/last30days',+ 'Last Day': '/admin/ext-uninstall-reasons/lastday',+};+</script>++<AnalyticsPage data={data.counts} title="Most Common Reasons to Uninstall the Chrome Ext" {links}/>diff --git a/packages/web/src/routes/admin/problematic-lints/[slug]/+page.server.ts b/packages/web/src/routes/admin/problematic-lints/[slug]/+page.server.tsnew file mode 100644index 000000000..32f684802--- /dev/null+++ b/packages/web/src/routes/admin/problematic-lints/[slug]/+page.server.ts@@ -0,0 +1,42 @@+import { redirect } from '@sveltejs/kit';+import ProblematicLints from '$lib/db/models/ProblematicLints';++export const load = async ({ params }) => {+ const slug = params.slug;++ let date = null;++ switch (slug) {+ case 'last30days':+ date = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);+ break;+ case 'lastday':+ date = new Date(Date.now() - 24 * 60 * 60 * 1000);+ break;+ case 'all':+ date = new Date(0);+ break;+ }++ if (date == null) {+ redirect(302, '/admin/problematic-lints/all');+ }++ const problematicLints = await ProblematicLints.getAllSince(date);++ const counts: Record<string, number> = {};++ for (const item of problematicLints) {+ const id = item.rule_id ?? 'OTHER';++ if (counts[id] === undefined) {+ counts[id] = 1;+ } else {+ counts[id] += 1;+ }+ }++ return {+ counts,+ };+};diff --git a/packages/web/src/routes/admin/problematic-lints/[slug]/+page.svelte b/packages/web/src/routes/admin/problematic-lints/[slug]/+page.sveltenew file mode 100644index 000000000..6e8f103a4--- /dev/null+++ b/packages/web/src/routes/admin/problematic-lints/[slug]/+page.svelte@@ -0,0 +1,13 @@+<script lang="ts">+import AnalyticsPage from '$lib/components/AnalyticsPage.svelte';+import type { PageProps } from './$types';++let { data }: PageProps = $props();+let links = {+ All: '/admin/problematic-lints/all',+ 'Last 30 Days': '/admin/problematic-lints/last30days',+ 'Last Day': '/admin/problematic-lints/lastday',+};+</script>++<AnalyticsPage data={data.counts} title="Most Reported Erroring Lint IDs" {links}/>diff --git a/packages/web/src/routes/docs/contributors/website/+page.md b/packages/web/src/routes/docs/contributors/website/+page.mdindex bd0038839..0c2d6ac5d 100644--- a/packages/web/src/routes/docs/contributors/website/+page.md+++ b/packages/web/src/routes/docs/contributors/website/+page.md@@ -1,154 +1,64 @@-----title: Website------This page describes how to develop [writewithharper.com](https://writewithharper.com) locally.-If you are comfortable with JavaScript or TypeScript but new to Svelte, start with [Prerequisites](#Prerequisites) and [Running the Site](#Running-the-Site), then skim [Where Code Lives](#Where-Code-Lives).--Make sure you read the [introduction to contributing](./introduction) and [committing](./committing) guides before opening a pull request.--## Notes--- Almost all website code lives under [`packages/web`](https://github.com/Automattic/harper/tree/master/packages/web).-- The site is a [SvelteKit](https://kit.svelte.dev/) app. Documentation pages use [SveltePress](https://sveltepress.site/) (Markdown routes under `src/routes/docs/`).-- The homepage demo and `/editor` route use workspace packages [`harper.js`](../../harperjs/introduction), [`lint-framework`](https://github.com/Automattic/harper/tree/master/packages/lint-framework), [`harper-editor`](https://github.com/Automattic/harper/tree/master/packages/harper-editor), and [`components`](https://github.com/Automattic/harper/tree/master/packages/components). `just dev-web` builds them for you.-- You can look at the project's [`justfile`](https://github.com/Automattic/harper/blob/master/justfile) to see exactly what the `just` recipes below do.-- CI builds the production site with the [`Build Web`](https://github.com/Automattic/harper/blob/master/.github/workflows/build_web.yml) workflow (Docker image from the root [`Dockerfile`](https://github.com/Automattic/harper/blob/master/Dockerfile)).--## Prerequisites--- [Set up your environment](./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--| Path | Purpose |-| --- | --- |-| `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.ts` | Vite 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:--```bash-just dev-web-```--This builds `harper.js`, `lint-framework`, `components`, and `harper-editor`, then runs `pnpm dev` in `packages/web`.--Open [http://localhost:3000](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:--```bash-just build-harperjs build-lint-framework build-components build-harper-editor-cd packages/web-pnpm install-pnpm dev-```--## Previewing Your Changes--| What you changed | Where to look |-| --- | --- |-| A documentation page | `http://localhost:3000/docs/...` (path mirrors `src/routes/docs/...`) |-| Homepage or marketing UI | `http://localhost:3000/` |-| Live grammar demo / editor | `http://localhost:3000/` (demo) or `http://localhost:3000/editor` |-| Rule catalog | `http://localhost:3000/docs/rules` |-| Weir studio | `http://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](https://svelte.dev/tutorial), [SvelteKit docs](https://kit.svelte.dev/docs).--## Testing and Validation--Before opening a pull request:--```bash-just format-just precommit-```--For website-focused checks:--```bash-cd packages/web-pnpm check-```--`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--```bash-just build-web-cd packages/web-pnpm preview-```--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](./review#Testing-Via-the-Docker-Image)):--```bash-docker build . -q-docker run -p 3000:3000 -it <image-id>-```--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--- [Harper's architecture](./architecture) — how `harper-core`, `harper.js`, and integrations fit together-- [Reviewing pull requests](./review) — testing patches, including the Docker demo workflow-- [`harper.js` documentation](../harperjs/introduction) — if you are wiring lint behavior on the site+---+title: Website+---++This page describes how to develop [writewithharper.com](https://writewithharper.com) locally.+Make sure you read the [introduction to contributing](./introduction) and [committing](./committing) guides before opening a pull request.++## Environment++Make sure you have [Set up your environment](./environment).++## Where Code Lives++| Path | Purpose |+| --- | --- |+| `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.ts` | Vite 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 navigation pane.++## Updating the Documentation++The Harper documentation (available on this site) is in `web/src/routes/docs`. It is written in Markdown.++## Running the Site++The recommended way to start a dev server:++```bash+just dev-web+```++This builds all the site's dependencies and runs a development server.+You do not need to rerun anything to hot-reload changes to the `web` package.+If you make changes to a dependency package (i.e. `components`, `harper-editor`), you MUST rerun `just dev-web` to see the changes appear on the development site.++> `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.++## Database++The web application needs a database available for some functionality, but not most.+You can spin up a development database locally using `docker-compose.dev.yml`.+You can make a copy of `docker-compose.yml` to run a full instance of the entire web application.++## Admin Pages++Admin pages, available at `/admin` are hidden by default, but can be enabled by setting the `ENABLE_ADMIN_ROUTES=true` environment variable before building the site.+At the time of writing, they are not admin routes as much as they are insights into the reports submitted by users.++## Deployment++Merges to `web-prod` trigger the **Build Web** workflow, which builds the root `Dockerfile` and publishes the site image via a private TeamCity instance.++## Related Reading++- [Harper's architecture](./architecture) — how `harper-core`, `harper.js`, and integrations fit together+- [Reviewing pull requests](./review) — testing patches, including the Docker demo workflow+- [`harper.js` documentation](../harperjs/introduction) — if you are wiring lint behavior on the site