Skip to content
New: Customize your theme with an AI assistant. Read the guide

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 engines in package.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:

Terminal window
node -v

The 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

  1. 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.json and AGENTS.md.

  2. Open a terminal inside that folder. In VS Code, use Terminal → New Terminal.

  3. Install the dependencies (only needed once, and again after updates):

    Terminal window
    npm ci

    npm ci installs the exact versions listed in package-lock.json. npm install works too.

  4. Start the development server:

    Terminal window
    npm run dev
  5. 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

Terminal window
npm run build
npm run preview

npm 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 placeholder https://example.com (Quick Start, step 1).
  • [forms]: a form still posts to a placeholder address (Quick Start, step 8).

Every Script, In Plain Words

CommandWhat it does
npm run devStarts the local site with live reload, and converts config.toml each time you save it
npm run buildBuilds 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 previewBuilds, then serves the production site locally
npm run astro-checkRuns 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-i18nChecks that every language has the same interface strings, menus, and content files
npm run formatTidies the formatting of files in src/
npm run generate-faviconsCreates every favicon size from [site.favicon] image in config.toml
npm run generate-og-imageRedraws the shared social image ([opengraph] image) with your logo, tagline, and description. Run it after you change them
npm run remove-multilingualDeletes every language except your default one, Arabic and French included. Read Internationalization first
npm run generate-multilingual-contentAdds 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-sitemapRemoves draft pages from the built sitemap. build already runs it
npm run indexnowTells Bing and other IndexNow search engines which pages changed. Needs [seo.ai] indexNowKey and a deployed site (see Deployment)
npm run deploy:cfUploads dist/ to Cloudflare Pages. Needs Wrangler installed first (see Deployment)
npm run toml:watchTurns 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.

Type something to search...