Websites

Nitric provides a simple way to deploy websites to the cloud, allowing you to serve website assets in a serverless environment without managing complex infrastructure.

If you're interested in the architecture, provisioning, or deployment steps, they can be found here.

Overview

Nitric’s website resource lets you:

• Serve static files (HTML, JS, CSS, images) from cloud storage.
• Serve your entire Nitric application from a single domain.
• APIs are automatically served under /api and websites are served under /.
• Deploy to various supported providers with minimal configuration.
• Use infrastructure from code to keep your environment consistent.

About API Routes

API route rewrites (under /api) are only enabled if you have at least one website defined in your project.
We are exploring options to allow enabling API routing independently of websites in the future.

Enabling Websites

Websites are currently in Preview. To enable this feature in your project add the following to your nitric.yaml file.

preview:
  - websites

Create a Website

1. Create your website project

Create a new website project using your preferred framework. For example, using Astro within your nitric project:

npm create astro@latest my-website

2. Add a website resources

Add a website resource to your nitric.yaml file.

websites:
  - basedir: ./my-website
    build:
      command: npm run build
      output: ./dist
    dev:
      command: npm run dev -- --port 4322
      url: http://localhost:4322

3. Start your website locally

Run nitric start to start your website locally. This will use the dev configuration, which proxies requests to your local development server.

Run nitric run command to run your production website locally. This will use the build configuration and serve the static files.

4. Deploy your website

Run nitric up to deploy your website to the cloud.

Sub Sites

You can also configure sub-sites under different paths. These will be deployed as subdirectories of the main site.

Here is an example configuration:

websites:
  - basedir: ./my-website
    build:
      command: npm run build
      output: ./dist
    dev:
      command: npm run dev -- --port 4322
      url: http://localhost:4322
  # the sub site is served under /docs, ensure you do not have conflicting routes
  - basedir: ./docs-website
    path: /docs
    build:
      command: npm run build
      output: ./dist
    dev:
      command: npm run dev -- --port 4323
      url: http://localhost:4323

Why Are All Sites Behind a Single Domain?

Currently, Nitric serves all websites behind a single domain to simplify deployment and management. This approach ensures that your API and website can coexist without CORS issues and allows for relative path usage in your frontend code. Additionally, serving all sites behind a single domain can reduce costs associated with managing multiple domains.

At this time, configuring multiple domains for different websites is not supported. However, we understand the need for this feature and may support multiple domains in the future.

Conflicting Routes

If you have conflicting routes between your API and website or between multiple sub-sites, you can configure the path for each website to avoid conflicts.

What Happens If There Are Overlapping Paths?

If Nitric detects overlapping paths between websites, an error will be raised during development and deployment.

However, client-side routes (like React Router) are not detected at deployment time — so be careful when designing single-page apps to avoid unexpected overlaps.

Reserved Paths

The following paths are reserved for use by the Nitric framework and cannot be used as website paths:

• /api - used to rewrite API requests

We are looking at making the rewrite path configurable in the future, so you will have more flexibility in defining your own path structure.

API Routes

If you have at least one website enabled, Nitric automatically serves your API under the /api path.

You can access your API routes at:

https://<your-cdn-endpoint>/api/<your-api>/<your-route>

When Are API Routes Enabled?

API route rewrites are only enabled if you have at least one website defined in your project.
We are exploring options to allow enabling API routing without requiring a website in the future.

Why This Approach?

By serving your API under the same domain as your website, you avoid CORS issues and can use relative paths to access your API directly from your frontend code.

Example API Call

async function fetchData() {
  // due to apis being served from the same domain thanks to rewrites, no CORS is required
  const response = await fetch('/api/main/hello')
  const data = await response.json()
  console.log(data)
}

Support for Frameworks like Next.js

If you're new to deploying websites with Nitric, you might wonder whether frameworks like Next.js will work by default.

• Built static websites (where your framework generates static assets, such as HTML, CSS, and JavaScript files) are fully supported.
• Server-side rendering (SSR) and framework-specific API routes (like Next.js API routes) are not currently supported.

If you are using Next.js, you can follow the official guide on static exports to generate a fully static version of your site.

We are actively exploring options to support server-side applications, including frameworks like Next.js, in the future.

Configuration

Here is a breakdown of the configuration options:

websites:
  - # The path to the website project directory
    basedir: ./my-website
    # The path to the website when deployed
    path: /
    # The default file to serve when no file is specified
    index: index.html
    # The file to serve when a 404 error occurs
    error: 404.html
    # The build options for the website
    build:
      # The command to build your website
      command: npm run build
      # The output directory for the build command
      output: ./dist
    # dev configuration is used by the `nitric start` command
    dev:
      # The command to run your website locally
      command: npm run dev -- --port 4322
      # The URL to access your website locally
      url: http://localhost:4322

Cloud Service Mapping

Each cloud provider comes with a set of default services used when deploying resources. You can find the default services for each cloud provider below.

• AWS
• Azure
• Google Cloud - Not implemented

If you need support for additional clouds or website types, let us know by opening an issue or joining the conversation on Discord.