Skip to content

Commit 07a4c91

Browse files
Josh-Walker-GMJosh-Walker-GM
committed
Version docs to 7.4
1 parent 7fb2deb commit 07a4c91

File tree

117 files changed

+46810
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

117 files changed

+46810
-0
lines changed

‎docs/versioned_docs/version-7.4/a11y.md

+170
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
slug: accessibility
3+
description: Accessibility is a core feature that's built-in
4+
---
5+
6+
# Accessibility (aka a11y)
7+
8+
We built Redwood to make building websites more accessible (we write all the config so you don't have to), but Redwood's also built to help you make more accessible websites.
9+
Accessibility shouldn't be a nice-to-have.
10+
It should be a given from the start.
11+
A core feature that's built-in and well-supported.
12+
13+
There's a lot of great tooling out there that'll not only help you build accessible websites, but also help you learn exactly what that means.
14+
15+
> **Does tooling obviate the need for manual testing?**
16+
>
17+
> No—even with all the tooling in the world, manual testing is still important, especially for accessibility.
18+
> But just because tooling doesn't catch everything doesn't mean it's not valuable.
19+
> It'd be much harder to learn what to look for without it.
20+
21+
## Accessible Routing
22+
23+
For single-page applications (SPAs), accessibility starts with the router.
24+
Without a full-page refresh, you just can't be sure that things like announcements and focus are being taken care of the way they're supposed to be.
25+
Here's a great example of [how disorienting SPAs can be to screen-reader users](https://www.youtube.com/watch?v=NKTdNv8JpuM).
26+
On navigation, nothing's announced.
27+
The lack of an announcement isn't just buggy behavior—it's broken.
28+
29+
Normally, the onus would be on you as a developer to announce to screen-reader users that they've navigated somewhere new.
30+
That's a lot to ask—and hard to get right—especially when you're just trying to build your app.
31+
32+
Luckily, if you're writing thoughtful content and marking it up semantically, there's nothing you have to do!
33+
The router automatically announces pages on navigation, and looks for announcements in this order:
34+
35+
1. The `RouteAnnouncement` component
36+
2. The page's `<h1>`
37+
3. `document.title`
38+
4. `location.pathname`
39+
40+
The reason for this order is that announcements should be as specific as possible.
41+
more specific usually means more descriptive, and more descriptive usually means that users can not only orient themselves and navigate through the content, but also find it again.
42+
43+
> If you're not sure if your content is descriptive enough, see the [W3 guidelines](https://www.w3.org/WAI/WCAG21/Techniques/general/G88.html).
44+
45+
Even though Redwood looks for a `RouteAnnouncement` component first, you don't have to have one on every page—it's more than ok for the `<h1>` to be what's announced.
46+
`RouteAnnouncement` is there for when the situation calls for a custom announcement.
47+
48+
### `RouteAnnouncement`
49+
50+
The way `RouteAnnouncement` works is simple: its children will be announced.
51+
Note that this can be something on the page or can be something that's visually hidden using the `visuallyHidden` prop:
52+
53+
```jsx title="web/src/pages/HomePage/HomePage.js"
54+
import { RouteAnnouncement } from '@redwoodjs/router'
55+
56+
const HomePage = () => {
57+
return (
58+
// This will still be visible
59+
<RouteAnnouncement>
60+
<h1>Welcome to my site!</h1>
61+
</RouteAnnouncement>
62+
)
63+
}
64+
65+
export default HomePage
66+
```
67+
68+
```jsx title="web/src/pages/AboutPage/AboutPage.js"
69+
import { RouteAnnouncement } from '@redwoodjs/router'
70+
71+
const AboutPage = () => {
72+
return (
73+
<h1>Welcome to my site!</h1>
74+
// This won't be visible
75+
// highlight-start
76+
<RouteAnnouncement visuallyHidden>
77+
All about me
78+
</RouteAnnouncement>
79+
// highlight-end
80+
)
81+
}
82+
83+
export default AboutPage
84+
```
85+
86+
`visuallyHidden` shouldn't be the first thing you reach for—it's good to maintain parity between your site's visual and audible experiences.
87+
But it's there if you need it.
88+
89+
## Focus
90+
91+
On page change, Redwood Router resets focus to the top of the DOM so that users can navigate through the new page.
92+
While this is the expected behavior (and the behavior you usually want), for some pages—especially those with a lot of navigation—it can be cumbersome for users to have tab through navigation before getting to the main point.
93+
(And that goes for every page change!)
94+
95+
Right now, there's two ways to alleviate this: with skip links or the `RouteFocus` component.
96+
97+
### Skip Links
98+
99+
Since the main content isn't usually the first thing on the page, it's a best practice to provide a shortcut for keyboard and screen-reader users to skip to it.
100+
Skip links do just that, and if you generate a layout using the `--skipLink` option, you'll get one with a skip link:
101+
102+
```
103+
yarn rw g layout main --skipLink
104+
```
105+
106+
```jsx title="web/src/layouts/MainLayout/MainLayout.js"
107+
import { SkipNavLink, SkipNavContent } from '@redwoodjs/router'
108+
import '@redwoodjs/router/skip-nav.css'
109+
110+
const MainLayout = ({ children }) => {
111+
return (
112+
<>
113+
<SkipNavLink />
114+
<nav></nav>
115+
<SkipNavContent />
116+
<main>{children}</main>
117+
</>
118+
)
119+
}
120+
121+
export default MainLayout
122+
```
123+
124+
`SkipNavLink` renders a link that remains hidden till focused and `SkipNavContent` renders a div as the target for the link.
125+
The code for these components comes from Reach UI. For more details, see [Reach UI's docs](https://reach.tech/skip-nav/#reach-skip-nav).
126+
127+
One thing you'll probably want to do is change the URL the skip link sends the user to when activated.
128+
You can do that by changing the `contentId` and `id` props of `SkipNavLink` and `SkipNavContent` respectively:
129+
130+
```jsx
131+
<SkipNavLink contentId="main-content" />
132+
{/* ... */}
133+
<SkipNavContent id="main-content" />
134+
```
135+
136+
If you'd prefer to implement your own skip link, [Ben Myers' blog](https://benmyers.dev/blog/skip-links/) is a great resource, and a great place to read about accessibility in general.
137+
138+
### `RouteFocus`
139+
140+
Sometimes you don't want to just skip the nav, but send a user somewhere.
141+
In this situation, you of course have the foresight that that place is where the user wants to be.
142+
So please use this at your discretion—sending a user to an unexpected location can be worse than sending them back the top.
143+
144+
Having said that, if you know that on a particular page change a user's focus is better off being directed to a particular element, the `RouteFocus` component is what you want:
145+
146+
```jsx title="web/src/pages/ContactPage/ContactPage.js"
147+
// highlight-next-line
148+
import { RouteFocus } from '@redwoodjs/router'
149+
150+
const ContactPage = () => (
151+
<nav>
152+
{/* Way too much nav... */}
153+
</nav>
154+
155+
// The contact form the user actually wants to interact with
156+
// highlight-start
157+
<RouteFocus>
158+
<TextField name="name" />
159+
</RouteFocus>
160+
// highlight-end
161+
)
162+
163+
export default ContactPage
164+
```
165+
166+
`RouteFocus` tells the router to send focus to it's child on page change. In the example above, when the user navigates to the contact page, the name text field on the form is focused—the first field of the form they're here to fill out.
167+
168+
<div class="video-container">
169+
<iframe src="https://www.youtube.com/embed/T1zs77LU68w?t=3240" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; modestbranding; showinfo=0; fullscreen"></iframe>
170+
</div>

‎docs/versioned_docs/version-7.4/app-configuration-redwood-toml.md

+194
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
---
2+
title: App Configuration
3+
description: Configure your app with redwood.toml
4+
---
5+
6+
# App Configuration: redwood.toml
7+
8+
One of the premier places you can configure your Redwood app is `redwood.toml`. By default, `redwood.toml` lists the following configuration options:
9+
10+
```toml title="redwood.toml"
11+
[web]
12+
title = "Redwood App"
13+
port = 8910
14+
apiUrl = "/.redwood/functions"
15+
includeEnvironmentVariables = []
16+
[api]
17+
port = 8911
18+
[browser]
19+
open = true
20+
[notifications]
21+
versionUpdates = ["latest"]
22+
```
23+
24+
These are listed by default because they're the ones that you're most likely to configure, but there are plenty more available.
25+
26+
You can think of `redwood.toml` as a frontend for configuring Redwood's build tools.
27+
For certain options, instead of having to configure build tools directly, there's quick access via `redwood.toml`.
28+
29+
## [web]
30+
31+
| Key | Description | Default |
32+
| :---------------------------- | :--------------------------------------------------------- | :---------------------- |
33+
| `title` | Title of your Redwood app | `'Redwood App'` |
34+
| `port` | Port for the web server to listen at | `8910` |
35+
| `apiUrl` | URL 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'` |
36+
| `includeEnvironmentVariables` | Environment variables made available to the web side during dev and build | `[]` |
37+
| `host` | Hostname for the web server to listen at | Defaults to `'0.0.0.0'` in production and `'::'` in development |
38+
| `apiGraphQLUrl` | URL to your GraphQL function | `'${apiUrl}/graphql'` |
39+
| `apiDbAuthUrl` | URL to your dbAuth function | `'${apiUrl}/auth'` |
40+
| `sourceMap` | Enable source maps for production builds | `false` |
41+
| `a11y` | Enable storybook `addon-a11y` and `eslint-plugin-jsx-a11y` | `true` |
42+
43+
### Customizing the GraphQL Endpoint
44+
45+
By default, Redwood derives the GraphQL endpoint from `apiUrl` such that it's `${apiUrl}/graphql`, (with the default `apiUrl`, `./redwood/functions/graphql`).
46+
But sometimes you want to host your api side somewhere else.
47+
There's two ways you can do this:
48+
49+
1. Change `apiUrl`:
50+
51+
```toml title="redwood.toml"
52+
[web]
53+
apiUrl = "https://api.coolredwoodapp.com"
54+
```
55+
56+
Now the GraphQL endpoint is at `https://api.coolredwoodapp.com/graphql`.
57+
58+
2. Change `apiGraphQLUrl`:
59+
60+
```diff title="redwood.toml"
61+
[web]
62+
apiUrl = "/.redwood/functions"
63+
+ apiGraphQLUrl = "https://api.coolredwoodapp.com/graphql"
64+
```
65+
66+
### Customizing the dbAuth Endpoint
67+
68+
Similarly, if you're using dbAuth, you may decide to host it somewhere else.
69+
To do this without affecting your other endpoints, you can add `apiDbAuthUrl` to your `redwood.toml`:
70+
71+
```diff title="redwood.toml"
72+
[web]
73+
apiUrl = "/.redwood/functions"
74+
+ apiDbAuthUrl = "https://api.coolredwoodapp.com/auth"
75+
```
76+
77+
:::tip
78+
79+
If you host your web and api sides at different domains and don't use a proxy, make sure you have [CORS](./cors.md) configured.
80+
Otherwise browser security features may block client requests.
81+
82+
:::
83+
84+
### includeEnvironmentVariables
85+
86+
`includeEnvironmentVariables` is the set of environment variables that should be available to your web side during dev and build.
87+
Use it to include env vars like public keys for third-party services you've defined in your `.env` file:
88+
89+
```toml title="redwood.toml"
90+
[web]
91+
includeEnvironmentVariables = ["PUBLIC_KEY"]
92+
```
93+
94+
```text title=".env"
95+
PUBLIC_KEY=...
96+
```
97+
98+
Instead of including them in `includeEnvironmentVariables`, you can also prefix them with `REDWOOD_ENV_` (see [Environment Variables](environment-variables.md#web)).
99+
100+
:::caution `includeEnvironmentVariables` isn't for secrets
101+
102+
Don't make secrets available to your web side. Everything in `includeEnvironmentVariables` is included in the bundle.
103+
104+
:::
105+
106+
## [api]
107+
108+
| Key | Description | Default |
109+
| :------------- | :---------------------------------- | :------------------------- |
110+
| `port` | Port for the api server to listen at | `8911` |
111+
| `host` | Hostname for the api server to listen at | Defaults to `'0.0.0.0'` in production and `'::'` in development |
112+
| `debugPort` | Port for the debugger to listen at | `18911` |
113+
| `serverConfig` | [Deprecated; use the [server file](./docker.md#using-the-server-file) instead] Path to the `server.config.js` file | `'./api/server.config.js'` |
114+
115+
## [browser]
116+
117+
```toml title="redwood.toml"
118+
[browser]
119+
open = true
120+
```
121+
122+
Setting `open` to `true` opens your browser to `http://${web.host}:${web.port}` (by default, `http://localhost:8910`) after the dev server starts.
123+
If you want your browser to stop opening when you run `yarn rw dev`, set this to `false`.
124+
(Or just remove it entirely.)
125+
126+
There's actually a lot more you can do here. For more, see Vite's docs on [`preview.open`](https://vitejs.dev/config/preview-options.html#preview-open).
127+
128+
## [generate]
129+
130+
```toml title="redwood.toml"
131+
[generate]
132+
tests = true
133+
stories = true
134+
```
135+
136+
Many of Redwood's generators create Jest tests or Storybook stories.
137+
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.
138+
These options allows you to disable the generation of test and story files.
139+
140+
## [cli]
141+
142+
```toml title="redwood.toml"
143+
[notifications]
144+
versionUpdates = ["latest"]
145+
```
146+
147+
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.
148+
And if you're on an experimental release line, like canary, there's new versions every day, multiple times.
149+
150+
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.
151+
152+
## Using Environment Variables in `redwood.toml`
153+
154+
You may find yourself wanting to change keys in `redwood.toml` based on the environment you're deploying to.
155+
For example, you may want to point to a different `apiUrl` in your staging environment.
156+
157+
You can do so with environment variables.
158+
Let's look at an example:
159+
160+
```toml title="redwood.toml"
161+
[web]
162+
// highlight-start
163+
title = "App running on ${APP_TITLE}"
164+
port = "${PORT:8910}"
165+
apiUrl = "${API_URL:/.redwood/functions}"
166+
// highlight-end
167+
includeEnvironmentVariables = []
168+
```
169+
170+
This `${<envVar>:[fallback]}` syntax does the following:
171+
172+
- sets `title` by interpolating the env var `APP_TITLE`
173+
- sets `port` to the env var `PORT`, falling back to `8910`
174+
- sets `apiUrl` to the env var `API_URL`, falling back to `/.redwood/functions` (the default)
175+
176+
That's pretty much all there is to it.
177+
Just remember two things:
178+
179+
1. fallback is always a string
180+
2. these values are interpolated at build time
181+
182+
## Running in a Container or VM
183+
184+
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:
185+
186+
```toml title="redwood.toml"
187+
[web]
188+
host = '0.0.0.0'
189+
[api]
190+
host = '0.0.0.0'
191+
```
192+
193+
You can also configure these values via `REDWOOD_WEB_HOST` and `REDWOOD_API_HOST`.
194+
And if you set `NODE_ENV` to production, these will be the defaults anyway.

0 commit comments

Comments
 (0)