Skip to content

Commit 4d19430

Browse files
devongovettdevongovett
authored
docs: Add getting started and framework setup guides (#9126)
* docs: Add getting started and framework setup guides * lint
1 parent 7898846 commit 4d19430

26 files changed

+1048
-108
lines changed

‎packages/@react-aria/i18n/src/useDefaultLocale.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,8 +80,9 @@ export function useDefaultLocale(): Locale {
8080
// We cannot determine the browser's language on the server, so default to
8181
// en-US. This will be updated after hydration on the client to the correct value.
8282
if (isSSR) {
83+
let locale = typeof window !== 'undefined' && window[localeSymbol];
8384
return {
84-
locale: 'en-US',
85+
locale: locale || 'en-US',
8586
direction: 'ltr'
8687
};
8788
}

‎packages/dev/parcel-transformer-s2-icon/IconTransformer.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ function template(asset, svg) {
8282
let normalizedPath = asset.filePath.replaceAll('\\', '/');
8383
let fn = asset.pipeline === 'illustration' || normalizedPath.includes('@react-spectrum/s2/spectrum-illustrations') ? 'createIllustration' : 'createIcon';
8484
return (
85-
`
85+
`"use client";
8686
import {${fn}} from '${normalizedPath.includes('@react-spectrum/s2') ? '~/src/Icon' : '@react-spectrum/s2'}';
8787
8888
${svg.replace('import { SVGProps } from "react";', '')}

‎packages/dev/s2-docs/pages/react-aria/frameworks.mdx‎

Lines changed: 372 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,372 @@
1+
import {Layout} from '../../src/Layout';
2+
export default Layout;
3+
4+
import {InstallCommand} from '../../src/InstallCommand';
5+
import {Command} from '../../src/Command';
6+
import {BundlerSwitcher, BundlerSwitcherItem} from '../../src/BundlerSwitcher';
7+
import {Tabs, TabList, Tab, TabPanel, Text} from '@react-spectrum/s2';
8+
import {StepList, Step, Counter} from '../../src/Step';
9+
import Nextjs from '../../src/icons/Nextjs';
10+
import ReactRouter from '../../src/icons/ReactRouter';
11+
import Vite from '../../src/icons/Vite';
12+
import Parcel from '../../src/icons/Parcel';
13+
import Webpack from '../../src/icons/Webpack';
14+
import Rollup from '../../src/icons/Rollup';
15+
import ESBuild from '../../src/icons/Esbuild';
16+
import Routers from '../../src/routers.mdx';
17+
18+
export const section = 'Guides';
19+
export const tags = ['framework', 'setup', 'routing', 'ssr'];
20+
export const description = 'Integrate React Aria with your framework';
21+
22+
# Framework setup
23+
24+
<PageDescription>How to integrate React Aria with your framework.</PageDescription>
25+
26+
<Tabs aria-label="Frameworks" density="compact">
27+
<TabList><Tab id="next"><Nextjs /><Text>Next.js</Text></Tab><Tab id="react-router"><ReactRouter /><Text>React Router</Text></Tab><Tab id="parcel"><Parcel /><Text>Parcel</Text></Tab><Tab id="vite"><Vite /><Text>Vite</Text></Tab><Tab id="webpack"><Webpack /><Text>webpack</Text></Tab><Tab id="rollup"><Rollup /><Text>Rollup</Text></Tab><Tab id="esbuild"><ESBuild /><Text>ESBuild</Text></Tab></TabList>
28+
<TabPanel id="next">
29+
To integrate with Next.js (app router), ensure the locale on the server matches the client, and configure React Aria links to use the Next.js router.
30+
31+
<StepList>
32+
<Step>
33+
<Counter />In your root layout, determine the user's preferred language and set the `lang` and `dir` attributes on the `<html>` element.
34+
35+
```tsx
36+
// app/layout.tsx
37+
import {headers} from 'next/headers';
38+
import {isRTL} from 'react-aria-components';
39+
import {ClientProviders} from './provider';
40+
41+
export default function RootLayout({children}) {
42+
// Get the user's preferred language from the Accept-Language header.
43+
// You could also get this from a database, URL param, etc.
44+
const acceptLanguage = (await headers()).get('accept-language');
45+
const lang = acceptLanguage?.split(/[,;]/)[0] || 'en-US';
46+
47+
return (
48+
<html lang={lang} dir={isRTL(lang) ? 'rtl' : 'ltr'}>
49+
<body>
50+
<ClientProviders lang={lang}>
51+
{children}
52+
</ClientProviders>
53+
</body>
54+
</html>
55+
);
56+
}
57+
```
58+
</Step>
59+
<Step>
60+
<Counter />Create `app/provider.tsx`. This should render an `I18nProvider` to set the locale used by React Aria, and a `RouterProvider` to integrate with the Next.js router.
61+
62+
```tsx
63+
// app/provider.tsx
64+
"use client";
65+
66+
import {useRouter} from 'next/navigation';
67+
import {RouterProvider, I18nProvider} from 'react-aria-components';
68+
69+
// Configure the type of the `routerOptions` prop on all React Aria components.
70+
declare module 'react-aria-components' {
71+
interface RouterConfig {
72+
routerOptions: NonNullable<Parameters<ReturnType<typeof useRouter>['push']>[1]>
73+
}
74+
}
75+
76+
export function ClientProviders({lang, children}) {
77+
let router = useRouter();
78+
79+
return (
80+
<I18nProvider locale={lang}>
81+
<RouterProvider navigate={router.push}>
82+
{children}
83+
</RouterProvider>
84+
</I18nProvider>
85+
);
86+
}
87+
```
88+
</Step>
89+
</StepList>
90+
</TabPanel>
91+
<TabPanel id="react-router">
92+
To integrate with React Router (framework mode), ensure the locale on the server matches the client, configure React Aria links to use client side routing, and exclude localized strings from the client bundle. If you're using declarative mode, choose your bundler above.
93+
94+
<StepList>
95+
<Step>
96+
<Counter />Run the following command to reveal [entry.server.tsx](https://remix.run/docs/en/main/file-conventions/entry.server) if you don't already have one.
97+
<Command command="npx react-router reveal" />
98+
</Step>
99+
<Step>
100+
<Counter />Make the following changes to `entry.server.tsx`. This will set the locale used by React Aria using the `Accept-Language` HTTP header, and inject the localized strings for the user's language into the HTML.
101+
102+
```tsx
103+
// app/entry.server.tsx
104+
import type {EntryContext} from 'react-router';
105+
import {ServerRouter} from 'react-router';
106+
import {renderToPipeableStream} from 'react-dom/server';
107+
/*- begin highlight -*/
108+
import {I18nProvider} from 'react-aria-components';
109+
import {getLocalizationScript} from 'react-aria-components/i18n';
110+
/*- end highlight -*/
111+
112+
export default async function handleRequest(
113+
request: Request,
114+
responseStatusCode: number,
115+
responseHeaders: Headers,
116+
remixContext: EntryContext,
117+
) {
118+
// Get the requested language (e.g. from headers, URL param, database, etc.)
119+
/*- begin highlight -*/
120+
const acceptLanguage = request.headers.get('accept-language');
121+
const lang = acceptLanguage?.split(/[,;]/)[0] || 'en-US';
122+
/*- end highlight -*/
123+
124+
return new Promise((resolve, reject) => {
125+
const {pipe, abort} = renderToPipeableStream(
126+
{/* Wrap in an I18nProvider to set locale used by React Aria. */}
127+
{/*- begin highlight -*/}
128+
<I18nProvider locale={lang}>
129+
{/*- end highlight -*/}
130+
<ServerRouter
131+
context={routerContext}
132+
url={request.url} />
133+
</I18nProvider>,
134+
{
135+
/*- begin highlight -*/
136+
// Inject localized strings into the HTML.
137+
bootstrapScriptContent: getLocalizationScript(lang),
138+
/*- end highlight -*/
139+
// ...
140+
}
141+
);
142+
});
143+
}
144+
```
145+
</Step>
146+
<Step>
147+
<Counter />In your root layout, set the `lang` and `dir` attributes on the `<html>` element, and render a `RouterProvider` to configure React Aria links to use React Router.
148+
149+
```tsx
150+
// app/root.tsx
151+
import {useLocale} from 'react-aria-components';
152+
import {useNavigate, useHref, type NavigateOptions} from 'react-router';
153+
154+
/*- begin highlight -*/
155+
// Configure the type of the `routerOptions` prop on all React Aria components.
156+
declare module 'react-aria-components' {
157+
interface RouterConfig {
158+
routerOptions: NavigateOptions
159+
}
160+
}
161+
/*- end highlight -*/
162+
163+
export function Layout({children}) {
164+
/*- begin highlight -*/
165+
let {locale, direction} = useLocale();
166+
let navigate = useNavigate();
167+
/*- end highlight -*/
168+
169+
return (
170+
/*- begin highlight -*/
171+
<html lang={locale} dir={direction}>
172+
{/*- end highlight -*/}
173+
<head>
174+
{/* ... */}
175+
</head>
176+
<body>
177+
{/*- begin highlight -*/}
178+
<RouterProvider navigate={navigate} useHref={useHref}>
179+
{/*- end highlight -*/}
180+
{children}
181+
</RouterProvider>
182+
{/* ... */}
183+
</body>
184+
</html>
185+
);
186+
}
187+
```
188+
</Step>
189+
<Step>
190+
<Counter />Install the locale optimization bundler plugin. This will omit the localized strings from the JavaScript bundle. The strings for the user's language are injected into the HTML instead.
191+
<InstallCommand pkg="@react-aria/optimize-locales-plugin" />
192+
</Step>
193+
<Step>
194+
<Counter />Edit `vite.config.ts` to add the plugin.
195+
196+
```ts
197+
// vite.config.ts
198+
import {reactRouter} from "@react-router/dev/vite";
199+
import {defineConfig} from 'vite';
200+
/*- begin highlight -*/
201+
import localesPlugin from '@react-aria/optimize-locales-plugin';
202+
/*- end highlight -*/
203+
204+
export default defineConfig({
205+
plugins: [
206+
reactRouter(),
207+
// Don't include any locale strings in the client JS bundle.
208+
/*- begin highlight -*/
209+
{...localesPlugin.vite({locales: []}), enforce: 'pre'}
210+
/*- end highlight -*/
211+
],
212+
});
213+
```
214+
</Step>
215+
</StepList>
216+
</TabPanel>
217+
<TabPanel id="parcel">
218+
To integrate with a client-only Parcel SPA, configure React Aria links to use your client side router, and optimize the client bundle to include localized strings for your supported languages.
219+
220+
<StepList>
221+
<Step>
222+
<Routers components={props.components} />
223+
</Step>
224+
<Step>
225+
<Counter />By default, React Aria includes localized strings for 30+ languages. To optimize the JavaScript bundle to include only your supported languages, install our bundler plugin.
226+
<InstallCommand pkg="@react-aria/parcel-resolver-optimize-locales" />
227+
</Step>
228+
<Step>
229+
<Counter />Add the following to your `.parcelrc`.
230+
231+
```json
232+
{
233+
"extends": "@parcel/config-default",
234+
"resolvers": ["@react-aria/parcel-resolver-optimize-locales", "..."]
235+
}
236+
```
237+
</Step>
238+
<Step>
239+
<Counter />In your project root `package.json`, add a `"locales"` field containing the languages you want to support.
240+
241+
```json
242+
{
243+
"locales": ["en-US", "fr-FR"]
244+
}
245+
```
246+
</Step>
247+
</StepList>
248+
</TabPanel>
249+
<TabPanel id="vite">
250+
To integrate with a client-only Vite SPA, configure React Aria links to use your client side router, and optimize the client bundle to include localized strings for your supported languages.
251+
252+
<StepList>
253+
<Step>
254+
<Routers components={props.components} />
255+
</Step>
256+
<Step>
257+
<Counter />By default, React Aria includes localized strings for 30+ languages. To optimize the JavaScript bundle to include only your supported languages, install our bundler plugin.
258+
<InstallCommand pkg="@react-aria/optimize-locales-plugin" />
259+
</Step>
260+
<Step>
261+
<Counter />Edit `vite.config.ts` to add the plugin, and configure the `locales` parameter.
262+
263+
```ts
264+
// vite.config.ts
265+
import {defineConfig} from 'vite';
266+
import localesPlugin from '@react-aria/optimize-locales-plugin';
267+
268+
export default defineConfig({
269+
plugins: [
270+
{
271+
...optimizeLocales.vite({
272+
locales: ['en-US', 'fr-FR']
273+
}),
274+
enforce: 'pre'
275+
}
276+
],
277+
});
278+
```
279+
</Step>
280+
</StepList>
281+
</TabPanel>
282+
<TabPanel id="webpack">
283+
To integrate with a client-only webpack SPA, configure React Aria links to use your client side router, and optimize the client bundle to include localized strings for your supported languages.
284+
285+
<StepList>
286+
<Step>
287+
<Routers components={props.components} />
288+
</Step>
289+
<Step>
290+
<Counter />By default, React Aria includes localized strings for 30+ languages. To optimize the JavaScript bundle to include only your supported languages, install our bundler plugin.
291+
<InstallCommand pkg="@react-aria/optimize-locales-plugin" />
292+
</Step>
293+
<Step>
294+
<Counter />Edit `webpack.config.ts` to add the plugin, and configure the `locales` parameter.
295+
296+
```ts
297+
// webpack.config.js
298+
const optimizeLocales = require('@react-aria/optimize-locales-plugin');
299+
300+
module.exports = {
301+
// ...
302+
plugins: [
303+
optimizeLocales.webpack({
304+
locales: ['en-US', 'fr-FR']
305+
})
306+
]
307+
};
308+
```
309+
</Step>
310+
</StepList>
311+
</TabPanel>
312+
<TabPanel id="rollup">
313+
To integrate with a client-only Rollup SPA, configure React Aria links to use your client side router, and optimize the client bundle to include localized strings for your supported languages.
314+
315+
<StepList>
316+
<Step>
317+
<Routers components={props.components} />
318+
</Step>
319+
<Step>
320+
<Counter />By default, React Aria includes localized strings for 30+ languages. To optimize the JavaScript bundle to include only your supported languages, install our bundler plugin.
321+
<InstallCommand pkg="@react-aria/optimize-locales-plugin" />
322+
</Step>
323+
<Step>
324+
<Counter />Edit `rollup.config.js` to add the plugin, and configure the `locales` parameter.
325+
326+
```ts
327+
// rollup.config.js
328+
import optimizeLocales from '@react-aria/optimize-locales-plugin';
329+
330+
export default {
331+
// ...
332+
plugins: [
333+
optimizeLocales.rollup({
334+
locales: ['en-US', 'fr-FR']
335+
})
336+
]
337+
};
338+
```
339+
</Step>
340+
</StepList>
341+
</TabPanel>
342+
<TabPanel id="esbuild">
343+
To integrate with a client-only ESBuild SPA, configure React Aria links to use your client side router, and optimize the client bundle to include localized strings for your supported languages.
344+
345+
<StepList>
346+
<Step>
347+
<Routers components={props.components} />
348+
</Step>
349+
<Step>
350+
<Counter />By default, React Aria includes localized strings for 30+ languages. To optimize the JavaScript bundle to include only your supported languages, install our bundler plugin.
351+
<InstallCommand pkg="@react-aria/optimize-locales-plugin" />
352+
</Step>
353+
<Step>
354+
<Counter />Edit your build script to add the plugin, and configure the `locales` parameter.
355+
356+
```ts
357+
import {build} from 'esbuild';
358+
import optimizeLocales from '@react-aria/optimize-locales-plugin';
359+
360+
build({
361+
// ...
362+
plugins: [
363+
optimizeLocales.esbuild({
364+
locales: ['en-US', 'fr-FR']
365+
})
366+
]
367+
});
368+
```
369+
</Step>
370+
</StepList>
371+
</TabPanel>
372+
</Tabs>

0 commit comments

Comments
 (0)