To install an Astro template and run it locally, extract the download, install its dependencies and start its development server from the project folder. This guide uses an example template running Astro 7.3.3 on a Mac. It also checks a production build so you can distinguish the editable development view from the finished static files.
You will need a terminal, a code editor and the version of Node.js required by your template. Read its README before following commands from another project. The folders and configuration file described here belong to the example template; your own template may organize content or site settings differently.
Steps to install an Astro template and run it locally
1. Check the required Node.js version
Open the template’s README and inspect the engines field in package.json. The example requires Node.js 22.18 or newer, with node >=22.18.0 in that field. Treat this as the requirement of the example project, rather than a number to impose on every Astro template you encounter.
In the terminal, run the following checks. npm comes with Node.js, and the commands show which versions are available in your current environment.
node -v
npm -v
Compare the results with your template’s requirements before installing dependencies. The captured example used Node.js v22.23.2 and npm 10.9.8; your output should be evaluated against your own project’s instructions.
2. Extract the ZIP and enter the project folder
Extract the downloaded ZIP; the unzip command can perform that step on the Mac used here. Use cd to move into the extracted project folder, then ls to list its contents. Substitute your actual folder name when changing directories, rather than looking for a universal Astro template folder name.
The example folder contains astro.config.ts, package.json, package-lock.json, README.md, public, src and tsconfig.json. Use those files as landmarks when checking your location. In particular, locate package.json before running the project’s npm commands, because it is where this template lists its scripts and dependencies.
3. Read the scripts and locate the source
The example’s package.json defines dev as astro dev, build as astro build and preview as astro preview. Its dependencies include Astro 7.3.3. Reading these entries connects the commands you will run with the project you extracted, instead of treating every npm command as an unexplained setup ritual.
In this example, src holds assets, components, content, data, layouts, lib, pages and styles, along with content.config.ts and site.config.ts. The pages folder turns files into pages, and content holds Markdown posts. The public folder contains files served as they are, including fonts and favicon.svg. Astro’s configuration lives in astro.config.ts.
4. Install the project’s dependencies
From the project folder, run the installation command below. It downloads dependencies into a new node_modules folder.
npm install
Wait for installation to finish and read the terminal output before starting the next command. Package totals, funding notices and audit results describe that particular installation; do not expect every template or later installation to repeat the counts from another project.
When you need the exact locked versions from package-lock.json, npm ci provides that installation route. Follow the template’s README when choosing the intended setup command. Keep the distinction between the source files you edit and the dependencies installed for the project clear as you inspect the folder afterward.
5. Start the server and open its address
Run the development script from the same project folder.
npm run dev
The example reports that Astro is ready, shows a local address at localhost:4321 and watches for file changes. Open the local address printed in your terminal in a browser. Keep the terminal visible so you can read what the server reports while you work on the site.
A small Astro toolbar appears at the bottom of the page in development mode. That toolbar belongs to the development view. At this stage you are inspecting the running source project locally, before making and reviewing the separate production build.
6. Make a small configuration change
In the example template, most site settings live in src/site.config.ts. Open that file in your code editor and change the site name, then save. With the development server running, the example reloads the browser automatically so the new name appears without a manual refresh.
Check your own README for the corresponding setting rather than assuming that every template uses site.config.ts. Make a small, recognizable change first so you can confirm the editing path before revising large amounts of content. Watch both the page and the terminal, and verify that the saved value is the one you see in the browser.
7. Build the site and inspect the output
Press Ctrl+C to stop the development server. Run the build command, wait for completion and inspect the output folder. Then start the local preview of that built site.
npm run build
ls dist
npm run preview
The example creates dist with HTML, CSS, images and fonts, including index.html and folders for the site’s pages and assets. Its captured build completed even though it printed a warning, so read the full outcome instead of assuming that a warning alone means failure. The preview script serves dist locally; inspect it after the build to check the finished files. A static host can serve this output, but deployment is outside this guide.
Common problems
Node.js version mismatch
Resolve the version requirement before continuing with dependency installation. Check both the README and package.json, then run node -v again to confirm the version available in the terminal you are using.
Different folder structure
Use ls and locate the extracted project’s package.json and README.md. Your template may have a different structure; follow its README rather than creating folders merely to match this example.
Source edit missing from the built preview
The development server watches source changes, while npm run preview serves the built dist folder. Run npm run build after the source change, then inspect the resulting output through preview.
FAQ
Do I need Node.js to install an Astro template and run it locally?
You need the Node.js version required by that template, along with a terminal and code editor. npm is included with Node.js.
Is src/site.config.ts a required file in every template?
That is where the example template keeps most site settings. Check your template’s README for its own configuration arrangement.
Does the development toolbar belong to the finished site?
The toolbar described here appears in development mode only. Use the build and preview steps to review the finished static output.
What does npm ci do differently from npm install here?
npm ci installs the exact versions recorded in package-lock.json. Follow the project instructions when choosing the installation workflow.
Summary
Confirm the runtime requirement, locate the extracted project and install its dependencies. Start development, make a small edit and watch the result. Finish by building dist and previewing that output so you have checked both the editing workflow and the generated site.
You can review the Astro portfolio collection for context on file-based sites built around project content.