Running Nuxas with Decap CMS Locally

Running Nuxas with Decap CMS Locally

This chapter is for readers who purchased the Code + Decap CMS edition. If you purchased the Code Only edition, you can skip this chapter and continue to the next one. The Code Only edition does not use Decap CMS, and everything you need is already running with npm run dev.

For those who purchased the CMS edition, this chapter shows you how to run Nuxas with Decap CMS on your own computer. This is called the local mode, and it is how you will edit content while you are developing.

Before we start, let us clarify what Decap CMS is and why it needs a separate server.

What Is Decap CMS?

Decap CMS is a browser-based content management system. It is a dashboard that lets you edit your blog, products, and site content without touching any files. Every change you make in the CMS is written back to the Markdown and YAML files in your project.

Because Decap CMS writes to files, it needs a way to save those files. In the local mode, it saves them directly to your computer, through a small server that you run in a separate terminal. In the cloud mode (after deployment), it saves them to your Git repository, through a service called Git Gateway.

This chapter covers the local mode. The cloud mode is covered in the deployment chapters later.

Why Two Terminals?

Running Nuxas with Decap CMS requires two servers running at the same time:

1. The Nuxt development server — this is the site itself, running on http://localhost:3000/. You start it with npm run dev.
2. The Decap CMS proxy server — this is a small server that lets the CMS save files to your computer. You start it with npx decap-server.

The two servers work together. The Nuxt server serves the site and the admin interface. The Decap server handles file writes. Without the Decap server, the CMS will open, but every save will fail with an error.

This is why we use two terminals: each terminal runs one server, and they run side by side.

Part 1 — Installing Decap Server

Before you can run the Decap proxy, you need to install it. This is a one-time step.

Open a terminal in VS Code. Make sure you are in the project root folder. Then run:

npm install decap-server --save-dev

This installs the decap-server package as a development dependency. You will see output like:

added 42 packages, and audited 885 packages in 30s

The exact numbers will differ, but the structure is the same. If you see a message like this, the installation succeeded.

You only need to run this command once. If you reinstall dependencies later with npm install, the Decap server will be reinstalled automatically because it is now listed in package.json.

Part 2 — Starting the Decap Server

Now that Decap server is installed, we can start it.

Open a new terminal in VS Code. You can do this from the menu: Terminal → New Terminal. Alternatively, click the + icon in the terminal panel.

You now have two terminals: the first one (the original) and the second one (the new one). Make sure you are running commands in the second terminal for this step.

In the second terminal, run:

npx decap-server

You should see output like:

Decap CMS Proxy Server listening on port 8081

This means the Decap proxy is running. It will stay running until you stop it with Ctrl + C.

Important: Do not close this terminal. The Decap proxy needs to stay running for the CMS to save files.

Part 3 — Starting the Nuxt Development Server

Now switch to the first terminal — the one you used for npm run dev in the previous chapters. If the server is not running, start it:

npm run dev

If the server is already running, you can leave it as it is. The Nuxt server and the Decap server can run side by side without conflict.

You should see output like:

  ➜ Local:    http://localhost:3000/

Part 4 — Opening the CMS

With both servers running, open your browser and go to:

http://localhost:3000/admin

You will see the Decap CMS login screen. In the local mode, there is no login — the CMS trusts your local machine. You will be taken directly to the dashboard.

The dashboard shows your collections:

• Site Settings — global site configuration (navbar, footer, homepage).
• Page Configs — configuration for the blog list and product list.
• Contact Page — the contact page content.
• 404 Page — the 404 error page content.
• Blog Posts — the blog collection.
• Products — the product collection.
• Static Pages — the static pages collection.

Click any collection to see its entries. Click an entry to edit it. When you save, the change is written to the corresponding file in your project, and the Nuxt development server reloads the page automatically.

Understanding the Local Mode

In the local mode, Decap CMS saves files directly to your computer. This means:

• You do not need a Git repository to use the CMS.
• You do not need an internet connection.
• Every save is immediate — there is no commit, no push, no waiting.

This is ideal for development. You can iterate on content quickly, see the results in the browser immediately, and commit your changes to Git when you are ready.

When you are ready to deploy, you will switch to the cloud mode, where Decap CMS saves changes to your Git repository instead. We will cover that in the deployment chapters.

Common Issues

Issue: "Cannot connect to Decap Server"

This means the Decap proxy is not running. Check the second terminal. If you do not see the "listening on port 8081" message, the server is not running. Start it again with npx decap-server.

Issue: "Port 8081 is already in use"

Another process is using port 8081. This could be a previous instance of Decap server that did not shut down cleanly. On Windows, you can find and kill the process with:

netstat -ano | findstr :8081
taskkill /PID <PID> /F

Replace <PID> with the process ID shown in the first command.

Issue: CMS opens but shows a blank page

This usually means there is a syntax error in public/admin/config.yml. Open the file in VS Code and look for red squiggly lines. YAML is very sensitive to indentation — a single misplaced space can break the entire file.

Issue: Changes in the CMS do not appear on the site

This can happen if the Nuxt development server is not running, or if it has crashed. Check the first terminal. If you see an error, fix it, then restart the server with npm run dev.

What to Expect in the Next Chapter

In the next chapter, we will start editing the site's content through Decap CMS. We will begin with the Global Site Config — the file that controls your navbar, footer, and homepage. This is where you will make your first real changes to the site.

If you purchased the Code Only edition, you can skip to the chapter after next, which covers editing the same content directly in files.

See you in the next chapter.