Bought an Astro theme and wondering where to start? This guide walks you through getting the source, installing its dependencies, and opening a working website on your own computer.
We use Kivorun, our Astro + Sanity marketing agency theme, as the example. By the end, you will have its local demo running and know how to check a production build. You do not need a Sanity account, hosting account, or domain for this first step.
The commands below match Kivorun v1.0. Other Astro themes may use different scripts or environment settings. Always check the README included with your chosen version.
Before you start
- A Windows, macOS, or Linux computer with an internet connection.
- Access to the Kivorun Astro + Sanity source repository after purchase.
- Node.js 24 LTS with npm. Use the 24.x release line recommended in the theme README.
- A code editor such as Visual Studio Code. GitHub Desktop is optional if you prefer cloning without terminal Git commands.
Kivorun’s website requires Node.js 22.12 or newer, but this guide uses the tested Node.js 24 setup. If you later choose its optional Cloudflare deployment package, use Node.js 24.22.0 or newer.
Download Node.js from the official website
1. Get access to your theme source
After purchasing Kivorun through Polar, open the benefits attached to your order. Find the GitHub access benefit, connect the GitHub account you want to use, and accept the repository invitation. Open the private repository while signed in to that same account.
The Astro + Sanity edition is a source-code product. Your purchase gives you the files to build and host your own website; it does not create a Sanity project or hosting account for you.
Option A: clone with GitHub Desktop
Install GitHub Desktop and sign in with the account that accepted the invitation. Choose File → Clone repository → URL, paste the repository URL below, choose a local folder, and click Clone.
https://github.com/RedSignalRed/Kivorun-Astro-Sanity.gitUse Repository → Show in Explorer on Windows or Show in Finder on macOS to locate the files. Open that folder in your code editor.
Option B: download a ZIP
On the GitHub repository page, choose Code → Download ZIP. Extract the archive, then open the extracted project folder in your code editor. ZIP downloads are snapshots; they do not receive updates automatically.
Keep the reusable theme source private. If you create your own GitHub repository for your website, make it private and follow the included commercial license.
2. Check Node.js and npm
After installing Node.js, open a new terminal. In Visual Studio Code, use Terminal → New Terminal. Run these commands one at a time:
node --version
npm --versionBoth commands should return version numbers. For the setup used here, the Node.js version begins with v24. If a command is not recognized, restart the terminal after installation and check that Node.js was added to your system PATH.
3. Open the correct project folder
Your terminal must be in the folder that contains package.json. In Kivorun, this folder also contains README.md, astro.config.mjs, src, public, studio, and docs. If you extracted a ZIP, make sure you are inside the project folder rather than the folder above it.
Open the entire project folder in your editor, then open its integrated terminal. You do not need to install Astro globally or create a new Astro project: the theme already includes the project configuration.
4. Install the website dependencies
npm ciThis installs the dependency versions recorded in package-lock.json. Wait for the command to finish before continuing. The node_modules folder is created automatically.
Keep the supplied package-lock.json. Do not delete it or upgrade packages just to get started. Using the included lockfile helps reproduce the template’s tested setup.This step installs the website dependencies only. Sanity Studio and the optional Cloudflare deployment tool have separate packages; you do not need to install them to preview the local demo.
5. Create your local environment file
Copy .env.example to a new file named .env in the project root. Keep .env.example as the template and edit the copy. Choose the command for your terminal:
macOS or Linux
cp .env.example .envWindows PowerShell
Copy-Item .env.example .envYou can also duplicate the file in your editor. If using Windows File Explorer, show file extensions so the result is .env rather than .env.txt.
Open .env and keep the content source set to local:
CONTENT_SOURCE=localThis loads the sample content included with Kivorun. Leave the Sanity credentials and project details unconfigured for now. Do not switch to sanity until you have set up your own project using docs/INSTALLATION.md.
Keep private tokens in local environment files or your host’s environment settings. Never commit them to GitHub or include them in screenshots.
6. Start the local website
npm run devKeep the terminal running. Astro prints a Local address, normally http://localhost:4321. Open the address printed in your terminal in your browser. If that port is already in use, Astro may use another port.
You should now see the Kivorun demo homepage, including its hero and sample content. Visit Services, Work, About, Insights, and Contact to get familiar with the theme. Changes to source files normally appear after you save them while the development server is running.
A localhost address is a preview on your computer, not a publicly hosted website. The included contact form also needs your chosen submission endpoint before it can deliver enquiries.
To stop the development server, return to the terminal and press Ctrl+C. Run npm run dev again whenever you want to resume.
7. Build and preview the production output
Stop the development server, then generate the static website:
npm run buildA successful build writes the website to dist. This is generated output; make your edits in src and the relevant content files rather than editing dist directly.
Preview that build locally:
npm run previewOpen the address printed in the terminal. This lets you inspect the generated website before deployment. Preview does not publish it online. After changing source files, build again to refresh the output.
Kivorun also includes npm run verify, which runs its code checks, tests, and website build. You can use it when you are ready to validate your changes.
Common installation problems
GitHub shows a 404 page
Check that you are signed in to the GitHub account connected to your purchase and have accepted the invitation. A private repository may show 404 when that account does not have access.
npm cannot find package.json
The terminal is probably in the wrong folder. Open the project directory containing package.json and run the command there.
npm ci fails
Check your Node.js version, internet connection, and the first error message. Confirm you are using the unmodified package.json and lockfile from the same theme version. If you need help, send the error message rather than deleting the lockfile or forcing package upgrades.
PowerShell blocks npm.ps1
If Node.js is installed but PowerShell reports that scripts are disabled, use npm.cmd in place of npm, or open Command Prompt. For example:
npm.cmd ci
npm.cmd run devThe preview asks for Sanity configuration
Check that .env is in the project root and CONTENT_SOURCE is set to local. Stop and restart the development server after changing environment values.
What to do next
You now have the theme running locally and can generate a production build. For the next stage, follow docs/INSTALLATION.md in your source: create your own Sanity project, configure the website and Studio, publish Site Settings, and optionally import the sample content.
Customization, CMS publishing, hosting, and contact form setup are covered in separate guides. Within your source, start with docs/CUSTOMIZATION.md, docs/HOSTING.md, and docs/FORMS.md. The README for your installed theme version remains the reference for its exact commands and requirements.
Explore the Kivorun Astro + Sanity live demo
Get Kivorun Astro + Sanity with an Unlimited Commercial License
Need help with your purchase or installation? Email redsignal.red1@gmail.com with the product name, your operating system, Node.js version, the command you ran, and the error message. Remove passwords, tokens, and other private information.
References
Share this article
