RedwoodJS

# App Configuration: redwood.toml

You can configure your Redwood app's settings in redwood.toml. By default, redwood.toml lists the following configuration options:

[web]
  title = "Redwood App"
  port = 8910
  apiUrl = "/.redwood/functions"
  includeEnvironmentVariables = []
[api]
  port = 8911
[browser]
  open = true

These are listed by default because they're the ones that you're most likely to configure. But there are plenty more available. The rest are spread between Redwood's webpack configuration files and @redwoodjs/internal's config.ts:

The options and their structure are based on Redwood's notion of sides and targets. Right now, Redwood has two fixed sides, API and Web, that target NodeJS Lambdas and Browsers respectively. In the future, we'll add support for more sides and targets, like Electron and React Native (you can already see them listed as enums in TargetEnum), and as we do, you'll see them reflected in redwood.toml. But right now, you'll most likely never touch options like target.

The idea is that, in the future, changes here will have cascading, "app-level" effects. Using generators as an example, based on your side and target, the generators will behave differently, but appropriately different.

For the difference between a side and a target, see Redwood File Structure.

You can think of redwood.toml as a convenience layer over Redwood's webpack configuration files. That is, for certain settings, instead of having to deal with webpack directly, we give you quick access via redwood.toml. Some of these settings are for development, some are for production, and some are for both. You can actually see this reflected in which webpack file each configuration option is referenced in—webpack.development.js, webpack.production.js, and webpack.common.js.

redwood.toml also serves a slightly larger purpose: it's used to determine the base directory of a Redwood project. So this file is what really makes a Redwood app a Redwood app. If you remove it and run yarn rw dev, you'll get an error:

Error: Could not find a "redwood.toml" file, are you sure you're in a Redwood project?

(So don't do that!)

# [web]

Configuration for the web side.

Key Description Default Context
title Title of your Redwood App 'Redwood App' both
host Hostname to listen on 'localhost' development
port Port to listen on 8910 development
path Path to the web side './web' both
target Target for the web side 'browser' both
apiUrl Specify the URL to your api-server. Can be an absolute path or FQDN '/.redwood/functions' production
apiGraphQLUrl Optional: URL or absolute path to GraphQL function, without trailing slash ${apiUrl}/graphql production
apiDbAuthUrl Optional: URL or absolute path to DbAuth function, without trailing slash ${apiUrl}/auth production
includeEnvironmentVariables Environment variables to whitelist both
fastRefresh Enable webpack's fast refresh true development
a11y Enable storybook addon-a11y and eslint-plugin-jsx-a11y true development

# API Paths

You have full control over the path to your serverless functions via apiUrl. You can specify it either as a path (below) or a URL:

[web]
  apiUrl = "/.redwood/functions"

When you're running your app locally, this gets aliased away (you can see exactly how in webpack.common.js (and here's the docs on Webpack's devServer.proxy, for good measure)).

When you run redwood setup deploy [provider] on the CLI, this path gets configured to the default for the provider you're configuring

# Customizing the GraphQL Endpoint

By default, Redwood constructs the GraphQL endpoint from apiUrl such that ./redwood/functions/graphql ends up being the default graphql endpoint. But sometimes you want to host your api side somewhere else, or even on a different domain. There's two ways you can do this:

a) Change apiUrl to your new domain

[web]
  apiUrl = "https://api.coolredwoodapp.com"

This means your Redwood project's web side (i.e. the frontend) points to the above domain, and tries to access the GraphQL endpoint at https://api.coolredwoodapp.com/graphql.

b) Change only the graphql endpoint

You can also change the GraphQL endpoint only (without affecting other things, like dbAuth):

[web]
  apiUrl = "/.redwood/functions"
+ apiGraphqlEndpoint = "https://coolrwapp.mycdn.com"

This is particularly useful if you'd like to use a CDN provider like GraphCDN in front of your api side, independent of the web side.

# Customizing the DbAuth Endpoint

If you're using dbAuth, you may decide to point your auth function (i.e. the serverless function used for login/signup) at a different host. To do this without affecting your GraphQL endpoint, you can add apiDbAuthUrl to your redwood.toml:

[web]
  apiUrl = "/.redwood/functions"
+ apiDbAuthUrl = "https://api.mycoolapp.com/auth"

Quick note: if you point your web side to a different domain, please make sure you have CORS headers configured. Otherwise browser security features may block requests from the client.

# includeEnvironmentVariables

[web]
  includeEnvironmentVariables = ['API_KEY']

Where API_KEY is defined in .env or .env.defaults:

API_KEY=...

includeEnvironmentVariables is the set of environment variables to whitelist for the web side. You can also prefix environment variables with REDWOOD_ENV_ (see Environment Variables).

# [api]

Configuration for the api side.

Key Description Default Context
host Hostname to listen on 'localhost' development
port Port to listen on 8911 development
path Path to the api side './api' both
target Target for the api side 'node' both

# [browser]

Configuration for the browser target.

Key Description Default Context
open Open the browser to web's host:port after the dev server starts false development

# open

[browser]
  open = true

Setting open to true like this will open the browser to web's host:port (by default, localhost:8910) after the dev server starts. If you want your browser to stop opening when you yarn rw dev, set this to false. Or just remove it entirely.

You can also provide the name of a browser to use instead of the system default. E.g., open = 'Firefox' will open Firefox regardless of which browser's the default on your system.

When you generate a new app, the open value is set to true. If you delete the open config from redwood.toml, it will default to false. For example, removing the line open = true disables automatic browser opening.

There's a lot more you can do here. For all the details, see Webpack's docs on devServer.open.

# [generate]

[generate]
  tests = true
  stories = true

Configuration for Generator "test" and "story" files. By default, the following Generators create Jest test and/or Storybook files (with mock data files when applicable) along with specific component file(s): component, cell, layout, page, sdl, and services. Understandably, this is a lot of files, and sometimes you don't want all of them, either because you don't plan on using Jest/Storybook, or are just getting started and don't want the overhead. These toml keys allows you to toggle the generation of test and story files on and off.

Key Description Default
tests Generate Jest test files true
stories Generate Storybook story files true

# Tests

Setting to true creates tests when the generate command is invoked.

# Stories

Setting to true creates stories for Storybook when the generate command is invoked.

# Running within a Container or VM

To run a Redwood app within a container or VM, you'll want to set both the web and api's host to 0.0.0.0 to allow network connections to and from the host:

[web]
  host = '0.0.0.0'
  ...
[api]
  host = '0.0.0.0'
  ...

# Using Environment Variables in redwood.toml

Sometimes you want to change your redwood.toml based on the environment you're deploying to. For example, you may want to point to a different apiUrl in your staging environment. You can do this with environment variables. Let's look at an example:

[web]
  title = "App running on ${APP_TITLE}"
  port = "${PORT:8910}"
  apiUrl = "${API_URL:/.redwood/functions}"
  includeEnvironmentVariables = []

This does the following:

  • sets title by interpolating the env var APP_TITLE
  • sets port to the env var PORT, falling back to 8910
  • sets apiUrl to the env var API_URL, falling back to /.redwood/functions (the default)

That's pretty much all there is to it. Just remember two things:

  1. fallbacks are always strings
  2. these values are interpolated at build time