Skip to content
ForgeDocs logoForgeDocs7.3.8

Run Project

Run Project

Section titled “Run Project”

After installing ForgeDocs, you can run it locally to see your site in action. This guide covers the three commands you’ll use most often: dev, build, and preview.

Start the Development Server

Section titled “Start the Development Server”

From your project folder, run:

Terminal window
npm run dev

You’ll see output like this:

  🚀 astro v5.0.0 started in 342ms


  ┃ Local    http://localhost:4321/
  ┃ Network  http://192.168.1.10:4321/

Open your browser and go to:

http://localhost:4321

You should see the ForgeDocs homepage.

What the Development Server Does

Section titled “What the Development Server Does”

The development server:

  • Watches your files — when you save a change, the browser reloads automatically
  • Shows errors — if something breaks, you’ll see it in the terminal and browser
  • Serves your site at localhost:4321 — no build step needed

Keep this server running while you work. Changes appear instantly.

Stop the Development Server

Section titled “Stop the Development Server”

To stop the server, press:

Ctrl + C

You’ll return to your regular terminal prompt.

Build for Production

Section titled “Build for Production”

When you’re ready to deploy, build the production version:

Terminal window
npm run build

This creates a dist/ folder with your optimized site. The build process:

  • Compiles all pages to static HTML
  • Optimizes images
  • Minifies CSS and JavaScript
  • Generates a sitemap
  • Runs Pagefind to build the search index

You’ll see output like:

✓ Completed in 3.21s

The dist/ folder is what you upload to your hosting provider.

Preview the Production Build

Section titled “Preview the Production Build”

Before deploying, you can preview what the production build looks like:

Terminal window
npm run preview

This starts a local server that serves the contents of dist/. Open:

http://localhost:4321

The preview server is faster than the dev server because it’s serving static files — the same way your live site will be served.

Important: The preview server does not watch for file changes. If you edit files, you need to rebuild (npm run build) and restart the preview (npm run preview).

The Three Commands

Section titled “The Three Commands”

Here’s a quick reference:

Command What it does
npm run dev Start development server at localhost:4321
npm run build Build production site into dist/
npm run preview Preview the production build locally

When to Use Each Command

Section titled “When to Use Each Command”

During development — use npm run dev. Changes appear instantly.

Before deploying — use npm run build. Verify the build completes without errors.

After building — use npm run preview. Check that the production version looks correct.

On your live site — you don’t run any commands. Your hosting provider runs npm run build automatically every time you push changes to GitHub.

Common Issues

Section titled “Common Issues”

Port 4321 is already in use

Section titled “Port 4321 is already in use”

Another process is using port 4321. Either stop the other process, or start ForgeDocs on a different port:

Terminal window
npm run dev -- --port 3000

Then open http://localhost:3000.

Changes don’t appear in the browser

Section titled “Changes don’t appear in the browser”

Try a hard refresh:

  • Windows: Ctrl + Shift + R
  • macOS: Cmd + Shift + R

If that doesn’t work, stop the dev server (Ctrl + C) and restart it.

Build fails

Section titled “Build fails”

Check the terminal output for the error message. Common causes:

  • Missing dependency — run npm install again
  • Syntax error in a Markdown or JSON file — check the file mentioned in the error
  • Node.js version too old — verify with node --version

What’s Next

Section titled “What’s Next”

Now that you can run ForgeDocs, let’s set up the project:

→ First Setup

If you want to set up Decap CMS:

→ Decap CMS Local

Need Help?

Section titled “Need Help?”

If you’re stuck: