# General Translation React SDKs (gt-react, gt-next, gt-react-native): Configuring a webpack SPA
URL: https://generaltranslation.com/en-US/docs/react/guides/spa/configuring-webpack-spa.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: How to configure gt-react in a webpack-powered single-page React application.

Configure the application runtime and optionally bundle generated translation catalogs with your webpack build.

This guide prepares the application runtime. Mark user-facing content for translation separately.

## React webpack SPA setup [#setup]

Initialize `gt-react` before the application entry point runs.

### 1. Install gt-react

Install the latest `gt-react` with the repository's preferred package manager. Skip this step when it is already installed.

### 2. Add a `gt.config.json` file to the root of the project

Add a `gt.config.json` file to the root of the project. This file will contain the configuration for the `gt-react` package.

The locales already present in the project or supplied to the setup task are authoritative. Preserve any existing `locales` and `defaultLocale` values. The values below are examples only. If the project has no locale configuration, do not infer locale requirements from these examples.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "de"]
}
```

The optional [`src`](/docs/cli/reference/config#src) field designates the source files GT scans for inline content; when omitted, it defaults to these JavaScript and TypeScript globs under `src`, `app`, `pages`, and `components`:

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "de"],
  "src": [
    "src/**/*.{js,jsx,ts,tsx}",
    "app/**/*.{js,jsx,ts,tsx}",
    "pages/**/*.{js,jsx,ts,tsx}",
    "components/**/*.{js,jsx,ts,tsx}"
  ]
}
```

### 3. Initialize the library

Initialize the library with [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) before the application renders or imports modules that use module-level translation functions.

Create a bootstrap file next to the application's existing entry file. In this example, the original entry is `src/main.tsx` and the new bootstrap file is `src/index.ts`. Point webpack's existing `entry` configuration at the bootstrap file. Preserve all other build settings and any existing entry-object structure.

```js title="webpack.config.mjs"
export default {
  // ...the project's existing options
  entry: './src/index.ts',
};
```

webpack commonly injects the built entry into HTML through `HtmlWebpackPlugin`, so do not add a second script tag when the project already uses an HTML plugin. If its HTML directly references the original source entry instead, update that reference to the bootstrap file.

Then initialize GT and dynamically import the original entry only after initialization finishes. The webpack reference application supports top-level await:

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';

await initializeGTSPA(gtConfig);

await import('./main'); // render the app only after GT is ready
```

If the existing webpack compilation target does not support top-level await, do not change it solely for this setup. Use an async bootstrap function instead:

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';

async function bootstrap() {
  await initializeGTSPA(gtConfig);
  await import('./main');
}

void bootstrap();
```

## Loading translations [#translations]

When [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) is called without a [`loadTranslations`](/docs/react/reference/functions/load-translations) function, the runtime loads translations from the General Translation CDN only when a [`projectId`](/docs/react/reference/config#project-id) is available. To ship catalogs in the application bundle, configure an output path and a matching loader. The steps below use `src/_gt/[locale].json`.

### 1. Update the config

Set `files.gt.output` to the location where the CLI should write generated translation files.

Only add or merge the `files.gt.output` setting. Preserve the project's existing `locales` and `defaultLocale`; the values shown below remain examples and must not replace the project's configured locales.

Typically in a webpack-powered application, the translations will be stored in the `src/_gt` directory. This allows webpack to include the translation modules in the application bundle.

```json title="gt.config.json"
{
  "locales": ["fr", "zh"],
  "defaultLocale": "en",
  "files": {
    "gt": {
      "output": "src/_gt/[locale].json"
    }
  }
}
```

### 2. Add the stubs

Create one empty JSON file for each target locale already configured in `gt.config.json`, excluding the default locale. These stubs let imports resolve before translation bundles exist. The `fr` and `zh` files below illustrate the example configuration from this guide; create files for the project's actual configured target locales instead. If no target locales are configured, do not invent locales or create placeholder files.

<Files>
  <Folder name="src">
    <Folder name="_gt">
      <File name="fr.json" />
      <File name="zh.json" />
    </Folder>
  </Folder>
</Files>

```json title="src/_gt/fr.json"
{}
```

```json title="src/_gt/zh.json"
{}
```

### 3. Add the loader

Create `src/loadTranslations.ts` to load the translations. It must resolve to the same output location configured in `files.gt.output`.

```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  const translations = await import(`./_gt/${locale}.json`);
  return translations.default;
}
```

### 4. Update the initializer

Update the initializer to use the new loader function. Preserve whichever top-level-await or async-function bootstrap form the application uses.

```ts title="src/index.ts"
import { initializeGTSPA } from 'gt-react';
import gtConfig from '../gt.config.json';
import loadTranslations from './loadTranslations';

await initializeGTSPA({ ...gtConfig, loadTranslations });

await import('./main');
```

## Next steps

- /docs/react/guides/spa/internationalizing-react-spa
- /docs/react/guides/developing-spa-translations
- /docs/react/guides/storing-translations
- /docs/react/guides/managing-locales

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.