Installation Guide
Skill level: Beginner · Time: 10 minutes
Plumbo comes in three editions: Astro, Tina, and Sanity. See Theme Editions. This page installs any of them.
You need two things on your computer: Node.js (the program that runs the theme) and a code editor to open the files. If you have never used a terminal before, read Tools You Need first.
Requirements
- Node.js, in the version your edition lists under
enginesinpackage.json:- Astro and Sanity editions: 22.12 or later
- Tina edition: 22 (22.23.4 or later) or 24. Tina’s command line tool supports only those two
- npm, which comes with Node.js. Plumbo ships a
package-lock.json, so use npm rather than Yarn or pnpm - A code editor. VS Code is a good free choice; Plumbo recommends its Astro, TOML, and Tailwind CSS extensions when you open the folder
Install Node.js
Download the LTS installer from nodejs.org and run it. Then open PowerShell and check the version:
node -vDownload the installer from nodejs.org, or use Homebrew:
brew install nodenode -vInstall Node.js with your package manager or the official installer, then check the version:
node -vThe result must be v22.12.0 or higher. For the Tina edition, it must be a v22 version from v22.23.4, or a v24 version.
Run Plumbo On Your Computer
-
Unzip the download and move the theme folder to wherever you keep your projects. Open it in your code editor. It is the folder that contains
package.jsonandAGENTS.md. -
Open a terminal inside that folder. In VS Code, use Terminal → New Terminal.
-
Install the dependencies (only needed once, and again after updates):
Terminal window npm cinpm ciinstalls the exact versions listed inpackage-lock.json.npm installworks too. -
Start the development server:
Terminal window npm run dev -
Open http://localhost:4321/ in your browser.
npm run dev creates the settings file from config.toml, watches config.toml for changes, and starts the site. In the Tina edition it also starts the editor at /admin/. In the Sanity edition, npm run dev starts only the site: use npm run dev:all to start the Studio too. See Tina and Sanity.
Leave the terminal running while you work. When you save a file, including src/config/config.toml, the browser updates on its own. Press Ctrl + C in the terminal to stop the server.
Port 4321 already in use? In the Astro edition, run npm run dev -- --port 4322. In the Tina edition, set PORT in .env. In the Sanity edition, set SITE_PORT in .env.
Build And Preview The Production Site
npm run buildnpm run previewnpm run build writes the finished site to the dist/ folder. npm run preview builds it again and serves it at http://localhost:4321/, so you can test it exactly as visitors will see it.
On a fresh copy, the build prints two kinds of yellow warnings. Both are expected on your computer, and both tell you what to set before you deploy:
[site]: the site URL is still the placeholderhttps://example.com(Quick Start, step 1).[forms]: a form still posts to a placeholder address (Quick Start, step 8).
Every Script, In Plain Words
| Command | What it does |
|---|---|
npm run dev | Starts the local site with live reload, and converts config.toml each time you save it |
npm run build | Builds the production site into dist/ and removes drafts from the sitemap. Warns while the site URL or a form address is still a placeholder |
npm run preview | Builds, then serves the production site locally |
npm run astro-check | Runs check-i18n, then checks components and the content files that have a schema for mistakes. It doesn’t check section files or the contact page file. Run it before you deploy |
npm run check-i18n | Checks that every language has the same interface strings, menus, and content files |
npm run format | Tidies the formatting of files in src/ |
npm run generate-favicons | Creates every favicon size from [site.favicon] image in config.toml |
npm run generate-og-image | Redraws the shared social image ([opengraph] image) with your logo, tagline, and description. Run it after you change them |
npm run remove-multilingual | Deletes every language except your default one, Arabic and French included. Read Internationalization first |
npm run generate-multilingual-content | Adds a language: it copies your default language’s content, menu, and labels, and adds the language to language.json. See Internationalization |
npm run remove-draft-from-sitemap | Removes draft pages from the built sitemap. build already runs it |
npm run indexnow | Tells Bing and other IndexNow search engines which pages changed. Needs [seo.ai] indexNowKey and a deployed site (see Deployment) |
npm run deploy:cf | Uploads dist/ to Cloudflare Pages. Needs Wrangler installed first (see Deployment) |
npm run toml:watch | Turns config.toml into .astro/config.generated.json. dev, build, astro-check, generate-og-image, and indexnow already run it |
The Tina edition adds npm run tina:generate, npm run tina:audit, and npm run setup:tina. The Sanity edition adds npm run dev:all, npm run setup, npm run studio, npm run import-seed, npm run sanity:validate, npm run build:preview, npm run start:preview, npm run studio:build, and npm run studio:deploy. Their guides are Tina and Sanity.
Next: Quick Start, to make the site yours in about 30 minutes.