---
schema_version: "1"
id: a0062501b559d56376a5946bf80e70d2c921784b923618f3f46d031c517ff0ef
title: Build Tools
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-build-tools.md
canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-build-tools.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: da560cafdc9f48172ee6015e3a117692e9e51901555a85a082dd3a5563d24750
products:
  - Composable Storefront
  - Salesforce APIs
---
# Build Tools

Storefront Next uses [Vite](https://vite.dev/) as its build tool, providing fast development builds through native ES modules and optimized production builds through Rollup. The toolchain includes native TypeScript support and Vitest for testing.

## Vite Configuration

The `vite.config.ts` file configures these plugins for your storefront.

- `reactRouter()`: Enables React Router 7 framework mode with file-based routing and Server-Side Rendering (SSR).
- `tailwindcss()`: Compiles Tailwind CSS styles.
- `tsconfigPaths()`: Resolves TypeScript path aliases like `@/components`.
- `storefrontNextPlugin()`: Prepares your build for deployment to Managed Runtime (MRT), including bundle formatting, manifest generation, and React Router compatibility patches.

You can add more [Vite plugins](https://vite.dev/plugins/) to customize your build.

```typescript
// vite.config.ts
import { defineConfig } from "vite";
import { reactRouter } from "@react-router/dev/vite";
import tailwindcss from "@tailwindcss/vite";
import tsconfigPaths from "vite-tsconfig-paths";
import storefrontNextPlugin from "@salesforce/storefront-next-dev";

export default defineConfig({
  plugins: [reactRouter(), tailwindcss(), tsconfigPaths(), storefrontNextPlugin()],
});
```

### Storefront Next Plugin Options

The `storefrontNextPlugin` accepts this optional configuration object.

```typescript
storefrontNextPlugin({
  readableChunkNames: true,
});
```

| Option               | Type      | Default | Description                                                                                 |
| -------------------- | --------- | ------- | ------------------------------------------------------------------------------------------- |
| `readableChunkNames` | `boolean` | `false` | Generate human-readable chunk file names for easier debugging. Useful with bundle analyzer. |

When `readableChunkNames` is enabled, chunk files are named based on their source location.

```
// With readableChunkNames: true
(package)-(react-router)-(dist)-chunk.a1b2c3.js
(components)-(ui)-(button)-index.d4e5f6.js

// Default (readableChunkNames: false)
chunk.a1b2c3.js
index.d4e5f6.js
```

### Vite Plugins

| Plugin                     | Purpose                                   |
| -------------------------- | ----------------------------------------- |
| `@react-router/dev/vite`   | React Router 7 framework mode integration |
| `@tailwindcss/vite`        | Tailwind CSS compilation                  |
| `vite-tsconfig-paths`      | TypeScript path alias resolution          |
| `storefrontNextPlugin`     | MRT deployment and bundle optimization    |
| `vite-plugin-bundlesize`   | Bundle size validation                    |
| `rollup-plugin-visualizer` | Bundle analysis visualization             |

## React Router Configuration

The `react-router.config.ts` file uses a preset that enforces standard configuration for B2C Commerce.

```typescript
// react-router.config.ts
import type { Config } from '@react-router/dev/config';
import { odysseyPreset } from '@salesforce/storefront-next-dev/react-router-preset';

export default {
    presets: [odysseyPreset()],
} satisfies Config;
```

The preset configures:

- `appDirectory: './src'` — App source directory
- `buildDirectory: 'build'` — Build output directory
- `serverModuleFormat: 'cjs'` — Server bundle format for MRT compatibility
- `ssr: true` — Server-side rendering enabled
- Middleware support enabled

## TypeScript Configuration

Storefront Next uses TypeScript with strict settings enabled by default.

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "paths": {
      "@/*": ["./src/*"],
      "@/config/server": ["./config.server.ts"]
    }
  }
}
```

The `@/*` path alias lets you import from the `src` directory using absolute paths:

```typescript
import { Button } from "@/components/ui/button";
import { useCart } from "@/hooks/use-cart";
```

## Testing with Vitest

Storefront Next uses [Vitest](https://vitest.dev/) for unit testing. Vitest integrates natively with Vite, sharing the same configuration and transformation pipeline.

Configure testing options in the `test` section of `vite.config.ts`.

```typescript
// vite.config.ts
export default defineConfig({
  // ... other config
  test: {
    globals: true,
    environment: "jsdom",
    setupFiles: ["./vitest.setup.ts"],
    include: ["**/*.{test,spec}.{ts,tsx}"],
    coverage: {
      reporter: ["text", "json", "json-summary"],
      include: ["src/**/*.{ts,tsx}"],
      exclude: ["src/**/*.d.ts", "src/components/ui/**/*", "src/**/*.stories.{ts,tsx}"],
    },
  },
});
```

## Development Commands

| Command                   | Description                                           |
| ------------------------- | ----------------------------------------------------- |
| `pnpm dev`                | Start development server with hot module replacement. |
| `pnpm build`              | Create a production build.                            |
| `pnpm start`              | Preview a production build locally.                   |
| `pnpm push`               | Deploy to MRT.                                        |
| `pnpm typecheck`          | Run TypeScript type checking.                         |
| `pnpm test`               | Run Vitest tests with coverage.                       |
| `pnpm bundlesize:test`    | Build and validate bundle sizes.                      |
| `pnpm bundlesize:analyze` | Build and visualize bundle composition.               |

## Source Maps

Production builds generate source maps by default. Source maps map minified code back to your original source files, giving you readable stack traces when errors occur.

### Configure Source Maps in Vite

Control source map generation in `vite.config.ts` using Vite's `[build.sourcemap](https://vite.dev/config/build-options.html#build-sourcemap)` option.

```typescript
// vite.config.ts
export default defineConfig({
  build: {
    sourcemap: true, // default
  },
  plugins: [reactRouter(), tailwindcss(), tsconfigPaths(), storefrontNextPlugin()],
});
```

| Value      | Behavior                                                                    |
| ---------- | --------------------------------------------------------------------------- |
| `true`     | Generates `.map` files alongside your build output. (Default)               |
| `"hidden"` | Generates `.map` files but omits the `sourceMappingURL` comment in bundles. |
| `false`    | Disables source map generation entirely.                                    |

### Enable Source Maps on Managed Runtime

Source maps are included in your deployed bundle, but MRT must be configured to use them at runtime. When enabled, MRT starts your server with the `--enable-source-maps` Node.js flag, which gives you original file names and line numbers in error stack traces.

#### Using Runtime Admin

1. Log in to [Runtime Admin](https://runtime.commercecloud.com).
2. Click your project.
3. Click your target environment.
4. Click **Environment Settings**.
5. In the Advanced section, click **Edit**.
6. Enable **Source Maps**.
7. Click **Update** and wait for the bundle to redeploy.

#### Using the Managed Runtime API

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
export MRT_API_KEY="$API_KEY"

npx @salesforce/b2c-cli mrt env update \
  --project my-storefront --environment staging --enable-source-maps
```

Alternatively, use the API:

```bash
curl -X PATCH \
https://cloud.mobify.com/api/projects/{project_id}/target/{target_id}/ \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data '{"enable_source_maps": true}'
```

## Bundle Size Monitoring

Storefront Next enforces bundle size limits to maintain performance. Configure limits in `package.json`.

```json
"bundlesize": {
    "server": [
        { "name": "**/*", "limit": "5 mB" }
    ],
    "client": [
        { "name": "assets/-root.*.js", "limit": "113 kB" },
        { "name": "**/*", "limit": "50 kB" }
    ]
}
```

Run `pnpm bundlesize:test` to validate that your build stays within limits. If a chunk exceeds the baseline 50-KB limit, add an explicit entry for that chunk with an approved limit.

To generate a visual treemap of your bundle composition, run `pnpm bundlesize:analyze`. This command helps you identify optimization opportunities.