Skip to content
Blacks

Installation

Install Blacks Astro JS Template

This guide walks you through installing Blacks on your local machine. It works on Windows, macOS, and Linux. No prior Astro experience required — if you can follow steps, you can install Blacks.

By the end, you’ll have your site running at http://localhost:4321 in your browser.

Before You Start

Make sure you have:

  1. The Blacks source code — downloaded from Gumroad. See Download if you haven’t yet.
  2. Node.js installed — the engine that runs Astro. We’ll cover this below.
  3. A code editor — we recommend VS Code. Notepad works too, but VS Code is much easier.

Step 1 — Install Node.js

Blacks runs on Node.js. Without it, nothing will work. If you already have Node.js installed, skip to Step 2.

Download Node.js

  1. Go to nodejs.org/en/download
  2. Download the LTS version for your operating system
    • Windows: .msi installer
    • macOS: .pkg installer
    • Linux: use your package manager or the .tar.gz build

Install Node.js

  1. Open the downloaded installer
  2. Click Next through every screen — the defaults are fine
  3. Click Install, then Finish

Verify

Open your terminal (see Step 2 if you don’t know how) and type:

Terminal window
node --version

You should see something like v20.x.x or v22.x.x. If you see an error, restart your computer and try again.

Step 2 — Open Your Terminal

The terminal is where you’ll type commands. Here’s how to open it on each OS:

Windows:

  • Click the Windows logo on your taskbar
  • Type cmd and press Enter

macOS:

  • Press Cmd + Space to open Spotlight
  • Type terminal and press Enter

Linux:

  • Press Ctrl + Alt + T
  • Or search “Terminal” in your applications

A black or white window will open. This is your terminal. You’ll type all commands here.

Step 3 — Go to Your Project Folder

You need to point your terminal at the folder where you extracted the Blacks source code.

Example — if your project is on the Desktop and the folder is named blacks:

Terminal window
cd C:\Users\pcname\Desktop\blacks

Replace pcname with your computer’s username and blacks with your actual project folder name.

Tip: If the path has spaces, wrap it in quotes:

Terminal window
cd "C:\Users\My Name\Desktop\blacks"

To verify you’re in the right folder, type:

Terminal window
dir

(On macOS/Linux, use ls.) You should see files like package.json, astro.config.mjs, and folders like src, public.

Step 4 — Install Dependencies

Now install the project’s dependencies — the libraries Astro needs to run.

Terminal window
npm install

Wait for the process to complete. It usually takes 30 seconds to 2 minutes. You’ll see a progress indicator and then a message like added 400 packages.

What just happened? npm downloaded every library listed in package.json and put them in a folder called node_modules. This folder is large — don’t move it manually.

Step 5 — Start the Development Server

Now start the local server that will run your site.

Terminal window
npm run dev

After a few seconds, you’ll see:

🚀 astro v4.x.x started in XXXms


┃ Local    http://localhost:4321/
┃ Network  use --host to expose

Keep this terminal open. The server stays running as long as this window is open. If you close it, the server stops.

Step 6 — Visit Your Site

Open your web browser and go to:

http://localhost:4321

You should see the Blacks template running locally on your machine.

Every change you make to a file will be reflected here automatically. Save a file, and the browser updates within a second.

Stopping the Server

When you’re done working:

  1. Go back to the terminal
  2. Press Ctrl + C
  3. The server stops

To start it again later, repeat Step 5 (npm run dev).

Common Installation Problems

ProblemSolution
node: command not foundNode.js isn’t installed, or you need to restart your terminal
npm: command not foundSame — reinstall Node.js and restart your terminal
EACCES permission errorRun the terminal as Administrator (Windows) or use sudo (macOS/Linux)
npm install hangsCheck your internet connection, then try npm cache clean --force and retry
Port 4321 is in useRun npm run dev -- --port 3000 to use a different port

Next Step

Your Blacks site is running locally. Continue to:

👉 Configuration — set your site title, logo, and navigation