ben/HowDoYouConvert
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: describe svelte workflow

Browse Source
This commit is contained in:
Codex
2026-03-07 07:48:04 +00:00
parent f978cadfc6
commit 858c940332
2 changed files with 52 additions and 187 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
hdyc-svelte/README.md
View File

@@ -1,42 +1,32 @@
# sv
# HowDoYouConvert.com – Svelte Front End
Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli).
This repository hosts the modern SvelteKit experience for **howdoyouconvert.com**. Every calculator is rendered by Svelte on the server and client; no third-party CMS or injected script is involved anymore.
## Creating a project
## Overview
- The front end lives in `hdyc-svelte`; it uses `@sveltejs/adapter-node` to run as a Node server.
- `src/routes/+page.svelte` renders the hero, search, and category grid, while `src/routes/[slug]/+page.svelte` renders the calculators themselves.
- Conversion metadata is centralized in `src/lib/data/calculators.ts`, which drives the UI, search, glossary, and slug-based routing.
If you're seeing this, you've probably already done this step. Congrats!
## Development
1. Install dependencies inside the `hdyc-svelte` folder (`npm install` is sufficient; feel free to swap `npm` for `pnpm` or `yarn`).
2. Run `npm run dev` while editing to get a localhost server with hot reloading.
3. Use `npm run check` to run `svelte-check` and surface type or markup issues.
4. When you are ready to verify the production bundle, run `npm run build` and optionally `npm run preview` or `npm run start` to exercise the compiled `build` folder.
```sh
# create a new project
npx sv create my-app
```
## Data pipeline
- The single source of truth for every published calculator is `calculators_list.md` in the repo root. The **Active Calculators** table at the top defines which conversions are shipped; the trailing backlog checklist stores future work.
- After editing `calculators_list.md`, run `python migrate.py` from the repo root. The script reads the registry, infers categories/types based on the conversion factor column, and writes the autogenerated `hdyc-svelte/src/lib/data/calculators.ts` file.
- `calculators.ts` contains the `calculators` array, the `categories` map, and helper lookup/search functions. **Do not edit it manually**—regenerate it through `migrate.py` whenever the registry changes.
- The generator also populates descriptions, hidden flags, and label metadata, so confirm the regenerated file before committing.
To recreate this project with the same configuration:
## Adding a calculator
1. Add a new row to the active table in `calculators_list.md`; the slug must be lowercase and dash-separated, and the conversion factor column must encode the math (`Linear Offset (m x + b)`, `1/x`, `Multi-Variable`, `10_to_2`, etc.).
2. Run `python migrate.py` so the new slug appears in `src/lib/data/calculators.ts` with the correct type and labels.
3. Start the dev server and navigate to `/new-slug` to verify the UI, bidirectional math, and description text.
4. Run `npm run check` (and optionally `npm run build`) before committing so the type system stays happy.
```sh
# recreate this project
npx sv@0.12.5 create --template minimal --types ts --install npm hdyc-svelte
```
## Deploying & verification
- The output of `npm run build` can be deployed anywhere that serves a Node app (a hosted environment or edge with Node support). `npm run start` runs the compiled server locally.
- For each release, make sure the generated data file and the registry are in sync. Any mismatch will result in missing calculator pages because the routing is slug-driven.
## Developing
Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
```sh
npm run dev
# or start the server and open the app in a new browser tab
npm run dev -- --open
```
## Building
To create a production version of your app:
```sh
npm run build
```
You can preview the production build with `npm run preview`.
> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
Maintaining the registry and the generated data file is the only path to publish a calculator in the new architecture.