Skip to main content
Version: 7.6

App Configuration: redwood.toml

One of the premier places you can configure your Redwood app is redwood.toml. By default, redwood.toml lists the following configuration options:

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

These are listed by default because they're the ones that you're most likely to configure, but there are plenty more available.

You can think of redwood.toml as a frontend for configuring Redwood's build tools. For certain options, instead of having to configure build tools directly, there's quick access via redwood.toml.

[web]

KeyDescriptionDefault
titleTitle of your Redwood app'Redwood App'
portPort for the web server to listen at8910
apiUrlURL to your api server. This can be a relative URL in which case it acts like a proxy, or a fully-qualified URL'/.redwood/functions'
includeEnvironmentVariablesEnvironment variables made available to the web side during dev and build[]
hostHostname for the web server to listen atDefaults to '0.0.0.0' in production and '::' in development
apiGraphQLUrlURL to your GraphQL function'${apiUrl}/graphql'
apiDbAuthUrlURL to your dbAuth function'${apiUrl}/auth'
sourceMapEnable source maps for production buildsfalse
a11yEnable storybook addon-a11y and eslint-plugin-jsx-a11ytrue

Customizing the GraphQL Endpoint

By default, Redwood derives the GraphQL endpoint from apiUrl such that it's ${apiUrl}/graphql, (with the default apiUrl, ./redwood/functions/graphql). But sometimes you want to host your api side somewhere else. There's two ways you can do this:

  1. Change apiUrl:
redwood.toml
[web]
apiUrl = "https://api.coolredwoodapp.com"

Now the GraphQL endpoint is at https://api.coolredwoodapp.com/graphql.

  1. Change apiGraphQLUrl:
redwood.toml
 [web]
apiUrl = "/.redwood/functions"
+ apiGraphQLUrl = "https://api.coolredwoodapp.com/graphql"

Customizing the dbAuth Endpoint

Similarly, if you're using dbAuth, you may decide to host it somewhere else. To do this without affecting your other endpoints, you can add apiDbAuthUrl to your redwood.toml:

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

If you host your web and api sides at different domains and don't use a proxy, make sure you have CORS configured. Otherwise browser security features may block client requests.

includeEnvironmentVariables

includeEnvironmentVariables is the set of environment variables that should be available to your web side during dev and build. Use it to include env vars like public keys for third-party services you've defined in your .env file:

redwood.toml
[web]
includeEnvironmentVariables = ["PUBLIC_KEY"]
.env
PUBLIC_KEY=...

Instead of including them in includeEnvironmentVariables, you can also prefix them with REDWOOD_ENV_ (see Environment Variables).

includeEnvironmentVariables isn't for secrets

Don't make secrets available to your web side. Everything in includeEnvironmentVariables is included in the bundle.

[api]

KeyDescriptionDefault
portPort for the api server to listen at8911
hostHostname for the api server to listen atDefaults to '0.0.0.0' in production and '::' in development
debugPortPort for the debugger to listen at18911
serverConfig[Deprecated; use the server file instead] Path to the server.config.js file'./api/server.config.js'

[browser]

redwood.toml
[browser]
open = true

Setting open to true opens your browser to http://${web.host}:${web.port} (by default, http://localhost:8910) after the dev server starts. If you want your browser to stop opening when you run yarn rw dev, set this to false. (Or just remove it entirely.)

There's actually a lot more you can do here. For more, see Vite's docs on preview.open.

[generate]

redwood.toml
[generate]
tests = true
stories = true

Many of Redwood's generators create Jest tests or Storybook stories. Understandably, this can be lot of files, and sometimes you don't want all of them, either because you don't plan on using Jest or Storybook, or are just getting started and don't want the overhead. These options allows you to disable the generation of test and story files.

[cli]

redwood.toml
[notifications]
versionUpdates = ["latest"]

There are new versions of the framework all the time—a major every couple months, a minor every week or two, and patches when appropriate. And if you're on an experimental release line, like canary, there's new versions every day, multiple times.

If you'd like to get notified (at most, once a day) when there's a new version, set versionUpdates to include the version tags you're interested in.

Using Environment Variables in redwood.toml

You may find yourself wanting to change keys in 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 so with environment variables. Let's look at an example:

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

This ${<envVar>:[fallback]} syntax 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. fallback is always a string
  2. these values are interpolated at build time

Running in a Container or VM

To run a Redwood app in 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:

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

You can also configure these values via REDWOOD_WEB_HOST and REDWOOD_API_HOST. And if you set NODE_ENV to production, these will be the defaults anyway.