Skip to main content

Migrating to Gesso v8

Gesso v8 represents a major modernization of the framework, migrating fully to ECMAScript Modules (ESM) and updating to the latest versions of core dependencies. This guide will help you upgrade your Gesso v7 project to v8.

Overview of Changes​

Gesso v8 introduces several significant updates:

  • Full ESM Migration: Complete move from CommonJS to ES Modules
  • Material UI v7: Upgraded from v6 to v7
  • React 19: Support for the latest React features
  • Node.js 22: Updated minimum Node version
  • TypeScript 5+: Better type checking and modern TypeScript features
  • Build System Modernization: Migrated from Rollup to tsup

Prerequisites​

Before upgrading, ensure you have:

  • Node.js 18+ (Node.js 22 recommended)
  • pnpm as your package manager
  • A working Gesso v7 project
  • Basic understanding of ESM vs CommonJS differences

Quick Start Upgrade Path​

1. Update Dependencies​

Update all Gesso packages to v8:

pnpm update "@acromedia/*@^8.0.0"

Or update your package.json manually:

{
  "dependencies": {
    "@acromedia/gesso": "^8.0.0",
    "@acromedia/gesso-bigcommerce": "^8.0.0",
    "@acromedia/gesso-next": "^8.0.0",
    // ... other gesso packages
  }
}

If your project directly uses Material UI components:

    "@mui/icons-material": "^7.3.1",
    "@mui/lab": "7.0.0-beta.16",
    "@mui/material": "^7.3.1",
    "@mui/system": "^7.3.1",
    "@mui/types": "^7.4.5",
    "@mui/utils": "^7.3.1",

Review MUI v7 Breaking Changes:

MUI v7 includes several breaking changes. Key updates to be aware of:

  • Updated theme structure and defaults
  • Changes to component prop types
  • Deprecated props removed
  • Updated CSS baseline

See the official MUI v7 migration guide for details.

3. Update Your TypeScript Configuration​

For Next.js projects, ensure you're using:

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

4. Update Next.js Config​

Since your project is now using ESM, you need to migrate your Next.js configuration file:

Step 1: Rename the Config File​

Rename next.config.js to next.config.mjs:

mv next.config.js next.config.mjs

Step 2: Convert CommonJS Syntax to ESM​

Update the file contents to use ESM syntax instead of CommonJS.

Before (next.config.js):

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  images: {
    domains: ['example.com'],
  },
}

module.exports = nextConfig

After (next.config.mjs):

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  images: {
    domains: ['example.com'],
  },
}

export default nextConfig

Common Patterns to Convert​

Pattern 1: Simple require statements

// Before:
const { PHASE_DEVELOPMENT_SERVER } = require('next/constants')

// After:
import { PHASE_DEVELOPMENT_SERVER } from 'next/constants'

Pattern 2: Dynamic configuration with require

// Before:
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
})

module.exports = withBundleAnalyzer({
  reactStrictMode: true,
})

// After:
import bundleAnalyzer from '@next/bundle-analyzer'

const withBundleAnalyzer = bundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
})

export default withBundleAnalyzer({
  reactStrictMode: true,
})

Pattern 3: Multiple plugin composition

// Before:
const withPWA = require('next-pwa')
const withBundleAnalyzer = require('@next/bundle-analyzer')

module.exports = withPWA(
  withBundleAnalyzer({
    pwa: {
      dest: 'public',
    },
    reactStrictMode: true,
  })
)

// After:
import withPWA from 'next-pwa'
import bundleAnalyzer from '@next/bundle-analyzer'

const withBundleAnalyzer = bundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
})

export default withPWA(
  withBundleAnalyzer({
    pwa: {
      dest: 'public',
    },
    reactStrictMode: true,
  })
)

Pattern 4: Conditional configuration

// Before:
module.exports = (phase, { defaultConfig }) => {
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      /* development only config */
    }
  }
  return {
    /* config for all phases */
  }
}

// After:
export default (phase, { defaultConfig }) => {
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      /* development only config */
    }
  }
  return {
    /* config for all phases */
  }
}

Common Migration Issues​

Issue: require is not defined​

Symptom: ReferenceError: require is not defined

Solution: Replace CommonJS requires with ESM imports:

// Before:
const module = require('./module')

// After:
import module from './module.js'

For dynamic requires, use dynamic imports:

// Before:
const module = require(dynamicPath)

// After:
const module = await import(dynamicPath)

Issue: __dirname is not defined​

Symptom: ReferenceError: __dirname is not defined

Solution: Use import.meta.url:

import { fileURLToPath } from 'node:url'
import { dirname } from 'node:path'

const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)

Issue: TypeError: e.alpha is not a function​

Symptom: Runtime error TypeError: e.alpha is not a function or similar MUI-related errors

Cause: Mismatched MUI package versions. This occurs when different MUI packages are on different major versions (e.g., @mui/material on v7 but @mui/system or @mui/utils still on v6).

Solution: Ensure all MUI packages are aligned to the same major version (v7 for Gesso v8):

update in your package.json:

{
  "dependencies": {
    "@mui/material": "^7.3.1",
    "@mui/icons-material": "^7.3.1",
    "@mui/system": "^7.3.1",
    "@mui/utils": "^7.3.1",
    "@mui/lab": "7.0.0-beta.16"
  }
}

Note: This issue can also occur if you have multiple versions of the same package installed due to dependency conflicts. The clean reinstall usually resolves this.

Need Help?​

If you encounter issues during migration:

  1. Check the ESM Migration Guide for detailed ESM migration steps
  2. Review the MUI v7 Migration Guide
  3. Check the Gesso package CHANGELOGs for specific breaking changes
  4. Reach out to the team via Slack or internal support channels

Additional Resources​

Last updated: January 2025