From repository to live site.

From the repository to a running site and a production build.

Requirements

Requirement	Version
Node.js	24.x
npm	11 or newer (ships with Node 24)
Git	Any recent version
Operating system	macOS, Linux, or Windows
Accounts or API keys	None, and no secrets. A production build needs the site's URL (step 4).

Check your versions:

node -v   # v24.x.x
npm -v    # 11.x.x

1. Get the source

Clone the Surch repository you were given access to, then start your own project from it. Your license does not allow the source in a public repository, and you cannot add anyone to the Surch repository, so your project lives in a private repository of your own:

git clone https://github.com/vlavera/surch.git my-cafe
cd my-cafe
git remote rename origin surch          # keep it, to pull future releases
git remote add origin <your own private repository>
git push -u origin main

2. Install dependencies

npm ci

npm ci installs the exact versions in package-lock.json. It reports two moderate vulnerabilities in test tooling. That is expected; read docs/TROUBLESHOOTING.md before doing anything about it.

3. Run the site locally

npm run dev

Open http://localhost:4321 (or the port it prints). You'll see the demo: a fictional coffee house, kept out of search, with every contact button inert and an order that sends nothing.

To run your own configuration once you've created it (docs/CUSTOMIZE.md):

SURCH_FIXTURE=client npm run dev                    # macOS / Linux
$env:SURCH_FIXTURE="client"; npm run dev            # Windows PowerShell

Stop the development server with Ctrl+C in the terminal where it runs.

4. Check and build

npm run typecheck          # TypeScript, the configuration's shape, and every language's copy
npm test                   # the configuration is coherent and its media files exist
SITE_URL=https://your-domain.com npm run build   # production build, into dist/
npm run preview            # serve the production build at http://localhost:4321 (Ctrl+C to stop)

npm run build and npm run dev check whichever configuration SURCH_FIXTURE makes active, and stop, naming the path, if it references a photo that is not in public/cafe/.

The site URL

npm run build needs to know where the site will live, because the page carries a canonical link that points there. It looks in this order:

1. SITE_URL in the environment, as in the command above (PowerShell: $env:SITE_URL="https://your-domain.com"; npm run build).
2. seo.siteUrl in your configuration (docs/CUSTOMIZE.md).
3. The project's production domain, when Vercel builds the site from a connected Git repository. A build run anywhere else does not have it.

If none of these gives a real https:// URL, the build stops and says so. There is no placeholder that quietly works. npm run dev does not need it.

Next steps

• Make it your own café: docs/CUSTOMIZE.md.
• Replace the example photos and understand their license: docs/ASSETS.md.
• Deploy: docs/DEPLOY.md.

Everything that makes a Surch site one café is in two places:

• The configuration, src/cafe/fixtures/*.ts: everything that is not a sentence. The name, the schedule, the parts of the day, the menu with sizes and prices, the counter, the photos, the currency, contact. Its shape is CafeContract in src/cafe/contract.ts, where every field is described.
• The copy, src/cafe/copy/en.ts, hy.ts, ru.ts: every sentence a visitor reads, one file per language. All three have the same keys (src/cafe/copy/types.ts); a key missing from one is a type error.

Surch builds to a static site (npm run build produces dist/): no server process, no adapter, no secrets. The build needs the site's URL. When Vercel builds the site from a connected Git repository it is picked up automatically; anywhere else, set SITE_URL (docs/INSTALL.md, "The site URL").

All notable changes to Surch are recorded here. Versions follow Semantic Versioning.

1.0.3

• The demo carries no notice. The line beside the order ("Sample ordering flow · …") is removed, with the note under the contact details and the caption on the drawn map panel. In a demo the order's "Send" and the contact buttons stay on the page and go nowhere, and the address reads "Sample address · your city".
• The address is no longer in the copy as shipped. find.address is empty in all three languages, and the Armenian and Russian copy no longer carries the example street in find.address, find.addressAlt or hero.eyebrow. A demo shows the shared sample line; a switched-on site shows what you write in find.address. If you have already written your address there, it is unaffected. find.sampleNote and find.mapNote are removed from the copy and its type.
• The demo is English-only by a stated rule, in src/cafe/locales.ts, with a test. Before, it was English-only because the notice had no Armenian or Russian translation.
• The shared code under src/chassis/ is version 0.9.0.

1.0.2

• One notice on the demo, not two. The line beside the Directions and Call buttons, added in 1.0.1, is removed. In a demo those buttons stay on the page and go nowhere; the notice beside the order remains. Nothing changes on a configured site.

1.0.1

• A second notice on the demo. While the site is a demo, the Directions and Call buttons now carry the line "Sample only · this demo sends nothing · …" beside them, as the order already carried its own. A switched-on site shows neither. Nothing changes on a configured site.
• The demo no longer prints a street address. The demo café does not exist, and its page gave a real street as its address. The English copy now reads "Sample address · your city", as a placeholder for yours, and the hero no longer names the street. The Armenian and Russian copy files still carry the old example address in find.address and hero.eyebrow; they are not published in the demo. Replace them with your own before publishing either language.
• docs/DEPLOY.md: the canonical link's fallback address is read when the site is built. If you attach a domain later and set neither SITE_URL nor seo.siteUrl, redeploy.
• The shared code under src/chassis/ is version 0.7.0.

1.0.0

First release.

• A one-page café site: the day in four parts, the coffee menu with sizes and prices, the counter, the room, and how to find the café.
• An order a visitor builds on the page and sends from their own WhatsApp. It is kept in their browser; nothing is charged and nothing is stored anywhere else. Ordering closes when the café does.
• Copy in English, Armenian and Russian. The demo is published in English. No one who reads Armenian or Russian is recorded as having read those translations (README.md, "Languages").
• Buyer guides in docs/, AGENTS.md for coding agents, and the license.

Known limitations

• One café, one page.
• No CMS: content is TypeScript files in src/cafe/.
• No payments, bookings or stock. Prices are content.
• Colours and typefaces are CSS, not configuration.
• The example photos are AI-generated and must be replaced before a commercial site goes live (LICENSE.md section 8).
• Deployment is verified on Vercel through its Git integration only.
• At 320 px wide the page scrolls sideways by a few pixels.