Migration 2.x → 3.0

This guide provides step-by-step instructions for migrating your Helium application from version 2.x to 3.0.

What Changed and Why

Change	Description
vite-plugin-ssr → Vike	Official rebrand by the maintainer with improved API and better documentation.
Vite 3 → Vite 5	Faster builds, improved HMR, enhanced TypeScript support.
Dependency Updates	Storybook v7→v8, i18next v21→v23, react-i18next v11→v13, GraphQL 16.6→16.11.
Enhanced Configuration	Vite config expanded with critical build settings and factory function pattern.

Prerequisites

• Backup your project (create a git branch)
• Node.js 18.20.7 required (check: node -v)
• npm 8.19.2+ (check: npm -v)
• Clean git state — commit or stash pending changes
• Working 2.x app that builds and runs successfully

Step 1: Update Dependencies

{
  "dependencies": {
    "@thoughtindustries/helium-server": "^3.0.0",
    "@thoughtindustries/catalog": "^2.0.0",
    "@thoughtindustries/content": "^2.0.0",
    "vike": "0.4.195",
    "vite": "^5.4.11",
    "i18next": "^23.16.8",
    "react-i18next": "^13.5.0"
  }
}

Remove old dependency and clean install:

npm uninstall vite-plugin-ssr
rm -rf node_modules package-lock.json
npm install

Step 2: Add Build Scripts

npm pack @thoughtindustries/helium-template@latest
tar -xzf thoughtindustries-helium-template-*.tgz package/scripts
mv package/scripts ./scripts
rm -rf package thoughtindustries-helium-template-*.tgz

Update build:vite in package.json:

"build:vite": "vite build && node scripts/generate-manifest.js && node scripts/generate-asset-tags.js"

Step 3: Update Imports

- import { escapeInject, dangerouslySkipEscape } from 'vite-plugin-ssr/server';
+ import { escapeInject, dangerouslySkipEscape } from 'vike/server';

Step 4: Update Vite Configuration

import { createVikeConfig } from '@thoughtindustries/helium-server';
import { defineConfig } from 'vite';

export default defineConfig(async () => {
  const config = await createVikeConfig();
  return config;
});

Step 5: Test and Deploy

rm -rf dist node_modules package-lock.json
npm install
npm run dev
npm run build
npm run deploy sandbox

Migration time

Most migrations take 1–4 hours depending on project size. The majority of time is testing, not code changes.