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.

1// vite.config.ts
2import { defineConfig } from "vite";
3import { reactRouter } from "@react-router/dev/vite";
4import tailwindcss from "@tailwindcss/vite";
5import tsconfigPaths from "vite-tsconfig-paths";
6import storefrontNextPlugin from "@salesforce/storefront-next-dev";
7
8export default defineConfig({
9  plugins: [reactRouter(), tailwindcss(), tsconfigPaths(), storefrontNextPlugin()],
10});

Storefront Next Plugin Options

The storefrontNextPlugin accepts this optional configuration object.

1storefrontNextPlugin({
2  readableChunkNames: true,
3});

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.

1// With readableChunkNames: true
2(package)-(react-router)-(dist)-chunk.a1b2c3.js
3(components)-(ui)-(button)-index.d4e5f6.js
4
5// Default (readableChunkNames: false)
6chunk.a1b2c3.js
7index.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.

1// react-router.config.ts
2import type { Config } from '@react-router/dev/config';
3import { odysseyPreset } from '@salesforce/storefront-next-dev/react-router-preset';
4
5export default {
6    presets: [odysseyPreset()],
7} 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.

1{
2  "compilerOptions": {
3    "target": "ES2022",
4    "module": "ES2022",
5    "moduleResolution": "bundler",
6    "jsx": "react-jsx",
7    "strict": true,
8    "noUnusedLocals": true,
9    "noUnusedParameters": true,
10    "paths": {
11      "@/*": ["./src/*"],
12      "@/config/server": ["./config.server.ts"]
13    }
14  }
15}

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

1import { Button } from "@/components/ui/button";
2import { 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.

1// vite.config.ts
2export default defineConfig({
3  // ... other config
4  test: {
5    globals: true,
6    environment: "jsdom",
7    setupFiles: ["./vitest.setup.ts"],
8    include: ["**/*.{test,spec}.{ts,tsx}"],
9    coverage: {
10      reporter: ["text", "json", "json-summary"],
11      include: ["src/**/*.{ts,tsx}"],
12      exclude: ["src/**/*.d.ts", "src/components/ui/**/*", "src/**/*.stories.{ts,tsx}"],
13    },
14  },
15});

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.

1// vite.config.ts
2export default defineConfig({
3  build: {
4    sourcemap: true, // default
5  },
6  plugins: [reactRouter(), tailwindcss(), tsconfigPaths(), storefrontNextPlugin()],
7});

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

Log in to Runtime Admin.
Click your project.
Click your target environment.
Click Environment Settings.
In the Advanced section, click Edit.
Enable Source Maps.
Click Update and wait for the bundle to redeploy.

Using the Managed Runtime API

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

Bundle Size Monitoring

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

1"bundlesize": {
2    "server": [
3        { "name": "**/*", "limit": "5 mB" }
4    ],
5    "client": [
6        { "name": "assets/-root.*.js", "limit": "113 kB" },
7        { "name": "**/*", "limit": "50 kB" }
8    ]
9}

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.