PageHare

PageHare turns your writing into a web page. Write in the editor, check the preview, and publish. Rules choose the layout without changing your words.

Start the app locally

Use Node.js 22 and npm 10 or later. Run these commands from the repository root:

npm install
cp packages/app/.env.example packages/app/.env
npm run dev

Open http://127.0.0.1:5173. Use this exact address for local sign-in. The app uses an AT Protocol account, such as a Bluesky account. Your account provider handles your password.

Write and publish

Sign in and choose New page.
Enter a title and body. Use headings, lists, links, images, or tables.
Wait for Saved locally. This saves a draft in this browser.
Open Preview to check the layout.
Choose Publish to make the page public.
Copy the published link to share it.

Drafts stay on this device. Clearing browser storage can remove them. Changes to a published page stay local until you choose Republish. Shared editing is planned; a published link does not grant edit access.

Published pages use https://<name>.pagehare.com/<title-slug>-<id> after you claim a name. Until then, they use /a/<did>/<title-slug>-<id>.

How the app works

SvelteKit and Svelte 5
run the app and render public pages.
Tiptap
provides the rich-text editor. Markdown is the saved content format.
AT Protocol
provides sign-in and stores published pages on your Personal Data Server (PDS). A DID is your account's stable identifier.
PageHare's block engine
chooses prose, headings, lists, and question-and-answer layouts. The preview and published page use the same rules.
PageHare's design system
controls type, spacing, and color through CSS tokens.
SST on AWS
deploys the app with Lambda, CloudFront, and S3. DynamoDB stores the publisher index, subdomain names, and analytics. It does not store page bodies.

For exact engine rules, read the block specification. For record fields and storage rules, read the storage guide.

Repository layout

Path	Purpose
`packages/app/`	Editor, public pages, settings, and server routes
`packages/core/`	Block engine, content conversion, and AT Protocol adapters
`lexicons/`	PageHare record schemas
`scripts/`	Build, validation, and maintenance tools
`docs/`	Guides, plans, specifications, and release history
`AGENTS.md`	Instructions for coding agents
`PAGEHARE_DS.md`	Required design-system rules

Commands

npm run dev             # Run the development app
npm run build           # Build the app for deployment
npm run check           # Check types and Svelte components
npm run lint            # Check formatting and code rules
npm run test            # Run unit and component tests
npm run e2e             # Run browser tests
npm run docs:html       # Build the HTML document library
npm run docs:watch      # Rebuild HTML when documents change
npm run docs:test       # Check the document generator

See the browser-test guide for test setup. Copy environment settings from packages/app/.env.example. A deployed PUBLIC_APP_URL must match the site's HTTPS address for sign-in to work.

Documentation

Start with the documentation index. It links to user guides, product status, technical rules, and operations guides.

Read the writing guide before creating or editing a document. Keep originals at their current paths and reading copies under docs/simplified/<original-path>. HTML uses the reading copies. A single-edition document (generated, append-only, or already plain) has no copy, and HTML uses the original. For a paired document, update both files, compare them, then run npm run docs:review -- <original-path>.

Deployment

Pushes to next deploy the preview. Pushes to main deploy production. The SST deployment guide explains credentials, domains, and failure recovery.

Contributing

Create a branch, make the change, update the relevant documents, and run the checks for your change. Open a pull request for review.