Deploying to Netlify

Deploying to Netlify

In the previous chapter, we pushed our code to GitHub. Now it is time to deploy the site to Netlify.

Netlify is the recommended hosting provider for Nuxas, especially if you purchased the Code + Decap CMS edition. Netlify provides two services that make cloud-mode Decap CMS trivial: Netlify Identity and Git Gateway. Identity handles user login, and Git Gateway lets Decap CMS write to your repository without requiring your editors to have GitHub accounts.

This chapter walks you through the entire process: choosing between SSG and SSR, creating a Netlify account, connecting your repository, configuring the build, enabling Identity, and activating Git Gateway.

Part 1 — Understanding SSG vs SSR Before You Deploy

Before you touch Netlify, you need to decide how your site will be built. Nuxt supports two deployment modes, and the build command you choose determines the mode. This is the single most important decision in the deployment process.

SSG (Static Site Generation)

• Build command: npm run generate
• Output folder: .output/public/
• What it produces: plain HTML, CSS, and JavaScript files. No server is needed at runtime.
• How it works: Nuxt pre-renders every page at build time. The result is a folder of static files that any static host (Netlify, Cloudflare Pages, Vercel, GitHub Pages, S3) can serve directly from a CDN.
• Pros: fastest possible response time (pure CDN), zero server cost, no cold starts, simplest to host.
• Cons: no server-side rendering at request time, no API routes, no dynamic per-request data. Content only updates when you rebuild.
• Best for: marketing sites, blogs, documentation, landing pages, and any frontend-only site where content is known at build time.

SSR (Server-Side Rendering)

• Build command: npm run build
• Output folder: .output/ (contains a Node.js server)
• What it produces: a portable Node.js server that renders pages on demand.
• How it works: Nuxt runs as a server. Each request is rendered on the fly, optionally using API routes, server middleware, cookies, and runtime environment variables.
• Pros: dynamic content, API routes, authentication, per-request logic, runtime environment variables.
• Cons: requires a Node.js runtime (serverless function or long-running server), slower cold starts on serverless, potentially higher cost.
• Best for: SaaS apps with login, dashboards, API routes, contact forms that send email server-side, and any site that needs runtime logic.

How Netlify handles each mode:

Netlify auto-detects Nuxt and, by default, suggests SSR (npm run build + dist). If you want SSG, you must explicitly change the build command to npm run generate and the publish directory to .output/public.

For a frontend-only Nuxas site (no API routes, no server middleware), SSG is the recommended mode. It is faster, cheaper, and simpler. The rest of this chapter assumes SSG. If you need SSR, replace the build settings with the SSR values shown in the table below.

Quick reference:

Part 2 — Creating a Netlify Account

1. Open your browser and go to https://www.netlify.com.
2. Click Sign up in the top right corner.
3. Choose Sign up with GitHub. This is the easiest option because you already have a GitHub account, and it lets Netlify access your repositories automatically.
4. Authorize Netlify to access your GitHub account. You can choose to grant access to all repositories or only specific ones. For Nuxas, granting access to the repository you created in the previous chapter is enough.
5. Once authorized, you will land on the Netlify dashboard.

Part 3 — Connecting Your GitHub Repository

1. On the Netlify dashboard, click Add new site, then Import an existing project.
2. Choose GitHub as your Git provider.
3. Netlify will show a list of your repositories. Find the repository you created in the previous chapter and click it.
4. Netlify will automatically detect that this is a Nuxt project and suggest build settings. Do not accept the defaults if you want SSG. Change them to:
   • Build command: npm run generate
   • Publish directory: .output/public
5. Click Deploy site.

If you skip step 4 and accept the defaults, Netlify will build your site as SSR (npm run build + dist). That is also valid, but it requires Netlify Functions and is unnecessary for a frontend-only site.

Netlify will start building your site. The first build takes a few minutes. You can watch the progress in the deploy log. When the build finishes, Netlify will show a URL like https://random-name-12345.netlify.app. Click it to see your site live on the internet.

Part 4 — Configuring the Site URL

Before we enable Identity and Git Gateway, let us update the site URL in your project.

1. Open nuxt.config.ts in VS Code.
2. Find the site block and update the url field to your Netlify URL:

site: {
  url: 'https://random-name-12345.netlify.app',
  name: 'My SaaS',
  description: 'My SaaS description',
  defaultLocale: 'en',
},

3. Save the file.
4. Commit the change and push it to GitHub:

git add .
git commit -m "Update site URL to Netlify domain"
git push

Netlify will automatically rebuild your site when it detects the push. Wait for the build to finish, then continue.

Part 5 — Enabling Netlify Identity

Netlify Identity is the service that handles user login for Decap CMS. Without it, the cloud mode of Decap CMS will not work.

1. On your Netlify dashboard, click your site.
2. In the top navigation, click Integrations, then Identity.
3. Click Enable Identity.
4. Once enabled, click Configuration and usage.
5. Under Registration, choose Invite only. This is the safest option: only users you explicitly invite can access the CMS.
6. Under External providers, you can optionally enable Google or GitHub login. This lets your editors log in with their existing accounts instead of creating a new password. For most users, this is a nice convenience, but it is not required.

Part 6 — Enabling Git Gateway

Git Gateway is the service that lets Decap CMS write to your repository. It works together with Identity: Identity verifies who the user is, and Git Gateway handles the actual file writes.

1. On the same Identity configuration page, scroll down to Services.
2. Find Git Gateway and click Enable Git Gateway.
3. Leave the Roles field blank. This means any logged-in Identity user can access the CMS. If you want to restrict access to specific roles, you can set them here, but for a small team, blank is fine.
4. Netlify will generate an API access token for your repository. This happens automatically. You do not need to do anything.

Part 7 — Inviting Your First CMS User

Now that Identity and Git Gateway are enabled, you need to invite yourself (or your client) as a CMS user.

1. In the Identity configuration page, click Invite users.
2. Enter the email address of the person who should have CMS access.
3. Click Send invite.
4. Check that email inbox. You will receive an invitation email from Netlify.
5. Click the link in the email. It will take you to your site's admin page.
6. Set a password. You will be logged in and taken to the Decap CMS dashboard.

If you chose Invite only registration, new users cannot sign up on their own. You must invite them from the Netlify dashboard. This is the recommended setup for production sites.

Part 8 — Testing the Cloud CMS

Now that you are logged in, let us test that the cloud CMS can write to your repository.

1. In the Decap CMS dashboard, open any collection (for example, Blog Posts).
2. Click an existing post.
3. Make a small change, such as adding a space to the title.
4. Click Save.
5. Go back to your GitHub repository. You should see a new commit from Netlify Identity, containing the change you just made.

If you see the commit, the cloud CMS is working correctly. If you see an error, check the following:

• Is Git Gateway enabled? (Part 6)
• Is the backend name in public/admin/config.yml set to git-gateway? It should already be, but double-check.
• Is the branch name in config.yml set to main? If your repository uses master, update it.

Part 9 — Verifying That SSG Is Actually Being Used

After the deploy finishes, confirm that Netlify built your site as SSG and not SSR:

1. Open the Deploys tab in your Netlify dashboard.
2. Click the latest deploy to open the deploy log.
3. Look for the build command line. It should say npm run generate, not npm run build.
4. Look for the publish directory. It should say .output/public.
5. On your live site, open DevTools → Network and reload. The initial HTML response should be served directly as a static file, with no serverless function invocation in the log.

If any of these checks fail, go back to Site settings → Build & deploy → Build settings and correct the build command and publish directory.

Part 10 — A Note on Netlify's Free Tier

Netlify's free tier includes:

• 100 GB of bandwidth per month
• 300 build minutes per month
• Unlimited Identity users
• Git Gateway

For most Nuxas users, the free tier is more than enough. If your site grows and you exceed these limits, Netlify offers paid plans with higher limits.

Troubleshooting

Issue: The CMS login page does not appear

Check that you have added the Netlify Identity widget to public/admin/index.html. It should include this line:

<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>

If it is missing, add it and redeploy.

Issue: "Git Gateway Error: 404"

This usually means the repository is not connected correctly. Go to Netlify's site settings, find the repository link, and relink it.

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

Netlify rebuilds the site automatically when it detects a commit. Check the Deploys tab in your Netlify dashboard. If the deploy failed, the change will not appear. Fix the build error and redeploy.

Issue: The site returns a 404 on refresh for deep routes

This usually means Netlify is not serving .output/public as a static site with SPA fallback. Confirm the publish directory is .output/public and that the build command is npm run generate. SSG output already contains a _redirects and 404.html file where needed; if you have a custom _redirects, make sure it does not override the SSG routing.

Issue: I see npm run build in the deploy log even though I wanted SSG

Netlify accepted its auto-detected defaults. Go to Site settings → Build & deploy → Build settings → Edit settings and change the build command to npm run generate and the publish directory to .output/public. Then trigger a new deploy.

What to Expect in the Next Chapter

In the next chapter, we will cover deploying to other hosting providers: Cloudflare Pages, Vercel, AWS, cPanel, and VPS. Each provider has its own setup, and we will walk through the most important ones, always keeping the SSG vs SSR distinction front and center.

If you are happy with Netlify, you can skip the next chapter and move to custom domain setup. But if you want to explore other options, read on.

See you in the next chapter.