FAQ and troubleshooting
npm install or npm run dev fails straight away
Section titled “npm install or npm run dev fails straight away”Check node -v. SwiftAgency needs Node.js 22.12 or newer. With an older version, installs can fail with engine or syntax errors. nvm or fnm make switching easy.
How do I hide the preset picker in the corner?
Section titled “How do I hide the preset picker in the corner?”Set theme.switcher to false in src/config/site.ts. It exists so theme buyers can try the presets on the demo; your visitors don’t need it.
Can I use it without Tailwind?
Section titled “Can I use it without Tailwind?”The components are written with Tailwind classes, so Tailwind stays. You don’t have to use it in your own components: plain CSS in a <style> block can use the same custom properties (rgb(var(--ink)), var(--font-display), var(--gutter)).
Content
Section titled “Content”The build fails with a message about a content file
Section titled “The build fails with a message about a content file”That is the schema doing its job. The message names the file and the field, for example summary: String must contain at most 160 characters. Fix that field and build again. Field rules are listed in Case studies and Journal.
An image can’t be found
Section titled “An image can’t be found”Image paths are relative to the content file. From src/content/projects/x.json it’s ../../assets/…; from a translation in src/content/projects/de/x.json it’s ../../../assets/…. Check for typos in the folder name, and that the file name’s case matches exactly: Cover.jpg and cover.jpg are different files on most hosts.
My German page shows English text
Section titled “My German page shows English text”That entry has no German translation yet, so the English version is shown on purpose. Add a file with the same name in the de/ folder. See Fallback. If it’s a button or heading instead, the German dictionary has an English value in it: search src/i18n/ui/de.ts.
I deleted a case study and the home page quote disappeared
Section titled “I deleted a case study and the home page quote disappeared”The home page quote comes from the Halden Rail testimonial, with any other testimonial as a fallback. If no project has a testimonial, the section is left out. Change the slug in src/pages/[...lang]/index.astro to feature a quote of your choice.
Keystatic
Section titled “Keystatic”/keystatic shows a blank page or a 404
Section titled “/keystatic shows a blank page or a 404”Keystatic only runs with the dev server. Make sure you started npm run dev or npm run cms, and that KEYSTATIC isn’t set to false in your environment. Try http://127.0.0.1:4321/keystatic rather than localhost, which is the address Keystatic’s own docs use.
Can clients edit the live site?
Section titled “Can clients edit the live site?”Yes, with some setup: Keystatic can save to GitHub instead of your disk. See Editing a deployed site.
Deploying
Section titled “Deploying”/work works locally but is a 404 on my host
Section titled “/work works locally but is a 404 on my host”The build writes work.html rather than work/index.html. Netlify, Vercel and Cloudflare are configured for this by the included config files. On another host, enable “clean URLs” or “pretty URLs”, or rewrite /work to /work.html. See Deploy.
Canonical URLs and social previews point at the SwiftAgency demo
Section titled “Canonical URLs and social previews point at the SwiftAgency demo”Set url in src/config/site.ts to your domain and redeploy.
The contact form says it sent, but nothing arrives
Section titled “The contact form says it sent, but nothing arrives”formEndpoint is empty, so the form is in demo mode. Connect it to a form service: see Contact form.
Performance
Section titled “Performance”Lighthouse gives me a lower score than the docs
Section titled “Lighthouse gives me a lower score than the docs”- Measure the production build with
npm run build && npm run preview, never the dev server. - Use a private window: browser extensions run on the page and count against it.
- Mobile scores vary a few points between runs. CI runs each page three times for that reason.
- Compare with the demo content. If your score dropped after adding content, see Keep it fast with your content.
How do I add analytics?
Section titled “How do I add analytics?”Add the provider’s script to the <head> in src/layouts/BaseLayout.astro, with defer or async. A lightweight, cookie-free service such as Plausible, Fathom or Umami keeps the scores and usually avoids a consent banner. Measure again after adding it.
Still stuck?
Section titled “Still stuck?”Check the changelog in case it’s something a newer version fixes, then get in touch through the channel you bought the theme from. Include your Node version, what you ran and the full error message.