Build Tools

Storefront Next uses Vite 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 to customize your build.

// 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.

storefrontNextPlugin({
  readableChunkNames: true,
});

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

React Router Configuration

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

// 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.

{
  "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:

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

Testing with Vitest

Storefront Next uses Vitest 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.

// 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

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.

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

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.
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:

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:

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.

"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.