Documentation

Migrate your Store Launchpad for B2C Retail to Next.js 14

Follow this guide to migrate your Store Launchpad for B2C Retail project to Next.js version 14.

Copy for LLM
View as Markdown
This guide outlines the changes to the Store Launchpad for B2C Retail and the steps required to migrate your project to Next.js version 14, including support for React Server Components and the App Router.

Migrating your project is not mandatory, but it is recommended to leverage the latest features and improvements.

We recommend referring to the Next.js App Router migration guide alongside this guide.

Overview of changes

Following is an overview of changes to the code for the Store Launchpad for B2C Retail to facilitate the migration to Next.js version 14. For steps to migrate your current B2C launchpad project, see Migration steps.

Transitioned from pages to app directory

The pages directory was transitioned to a new app directory. This included the following changes:

Relocated the catch-all route

  • Old path: packages/poc/frontend/pages/[[...slug]].tsx
  • New path: packages/poc/frontend/app/[locale]/[[...slug]]/page.tsx

This relocation includes the following key changes:

  • Data fetching: Replaced getServerSideProps with direct data fetching within components.
  • Metadata handling: Added a generateMetadata function for managing page metadata.
  • Locale integration: Introduced the [locale] dynamic route segment for locale-based routing.

Updated the i18n configuration

The next-i18next dependency for internationalization (i18n) handling was removed. The launchpad now uses the build-in capabilities of Next.js.
  • Old config path: packages/poc/frontend/next-i18next.config.js
  • New config path: packages/poc/frontend/i18n.config.ts

Added middleware for locales and cookies

A new middleware was added to handle locales and cookies:

  • New middleware path: packages/poc/frontend/middleware.ts

Updated layout files

A new layout.tsx file in the app directory is now used for shared UI components:
  • Old files: _app.tsx, _document.tsx
  • New file: packages/poc/frontend/app/[locale]/layout.tsx

Migrated the preview route

The preview route was moved to align with the new App Router structure:

  • Old path: packages/poc/frontend/pages/__preview/[previewId].tsx
  • New path: packages/poc/frontend/app/[locale]/__preview/[previewId]/page.tsx

Relocated sitemaps

The sitemaps were moved to the app directory to utilize Next.js's new routing system.
  • Static sitemap:
    • Old path: packages/poc/frontend/pages/sitemap-static.xml/index.tsx
    • New path: packages/poc/frontend/app/sitemap-static.xml/route.ts
  • Products sitemap:
    • Old path: packages/poc/frontend/pages/sitemap-products.xml/index.tsx
    • New path: packages/poc/frontend/app/sitemap-products.xml/route.ts
  • Categories sitemap:
    • Old path: packages/poc/frontend/pages/sitemap-categories.xml/index.tsx
    • New path: packages/poc/frontend/app/sitemap-categories.xml/route.ts

Updated hooks and utilities

Updated hooks

All hooks in helpers/hooks were updated to use the Next.js version 14 APIs.
  • New hook added: usePath (helpers/hooks/usePath)

Added a translation helper for React server components

A new helper for handling translations within React server components has been added:

  • New helper: helpers/i18n/get-translations.ts

Added Tailwind CSS class names utility

A utility for managing Tailwind CSS class names has been introduced:

  • New utility: packages/poc/frontend/helpers/utils/classnames.ts
Example CSS classnameJavaScript
const buttonClasses = classnames(
  'px-4 py-2 font-bold',
  isPrimary ? 'bg-blue-500 text-white' : 'bg-gray-200 text-black',
  {
    'opacity-50 cursor-not-allowed': isDisabled,
    'rounded-full': isRounded,
  }
);

// Resulting class string based on conditions
// e.g., 'px-4 py-2 font-bold bg-blue-500 text-white rounded-full'

Refactored the frontastic folder

Enhanced image component

The image component has been refactored into smaller, more manageable files and updated to use the latest next/image component.
  • Refactored component: packages/poc/frontend/frontastic/lib/image/

Realigned renderer components

The following components and functions for rendering were moved:

  • Moved components: cell, grid, and tastic components were moved to the packages/poc/frontend/frontastic/renderer/ folder.
  • Utility functions: Common functionalities such as device-visibility and highlight were converted into utility functions and are located at packages/poc/frontend/frontastic/renderer/utils/.

Refactored renderer component

The renderer component has been refactored and simplified.
  • Old path: packages/poc/frontend/frontastic/lib/renderer.tsx
  • New path: packages/poc/frontend/frontastic/renderer/index.tsx

Updated tastic components

All tastic components were updated to use new TypeScript types and the latest Next.js APIs such as next/navigation. The following is a list of the updated components:
  • Account components:
    • account/details
    • account/login
    • account/register
    • account/reset-password
  • Announcement bar:
    • bar/announcement
  • Cart component:
    • cart
  • Category slider:
    • category-slider
  • Checkout component:
    • checkout
  • Content components:
    • content/hero
    • content/tile
    • content/tiles-group
    • content-slider
  • Footer and header:
    • footer
    • header
  • Markdown renderer:
    • markdown
  • Newsletter component:
    • newsletter
  • Product components:
    • products/details
    • products/other-products
    • products/product-list
    • products/product-list-algolia
    • products/similar-products
    • products/slider
  • Showcase component:
    • showcase
  • Spacer component:
    • spacer

Migration steps

To incorporate the preceding changes, follow these steps to migrate your launchpad project:

Update the project structure

  1. Move all routes from the pages directory to the app directory as per the new paths.
  2. Add [locale] in your route segments where necessary. For example, packages/poc/frontend/pages/[[...slug]].tsx should become packages/poc/frontend/app/[locale]/[[...slug]]/page.tsx.

Refactor data fetching

  1. Remove getServerSideProps and fetch data directly within your components.
  2. Implement the generateMetadata function for page metadata.

Update locale configuration

  1. Replace next-i18next.config.js with i18n.config.ts.
  2. Update your imports and usages to use the new configuration.

Implement middleware

  1. Add middleware.ts to handle locale detection and cookie management.
  2. Ensure the middleware is correctly configured and placed in the root of the frontend directory.

Adjust layouts

  • In app/[locale]/, replace _app.tsx and _document.tsx with layout.tsx.
  • Move any global styles and scripts to the new layout.tsx file.

Update hooks and utilities

  1. Update custom hooks in helpers/hooks to use new Next.js APIs.
  2. Utilize the new translation helper in React Server Components.
  3. Use the classnames utility for managing Tailwind CSS classes.

Refactor frontastic components

  1. Update the image component to use the latest next/image features.
  2. Move the cell, grid, and tastic components to the renderer folder.
  3. Refactor common functionalities into utility functions.

Update Tastic components

  1. Update all tastic components to align with new TypeScript types.
  2. Replace deprecated Next.js APIs with the latest ones, such as next/navigation.

Test the application

  1. Run the application to ensure all routes and components function correctly.
  2. Verify that internationalization and middleware are working as expected.
  3. Check for any TypeScript errors and resolve them.

Check dependencies

  1. Ensure all your dependencies are updated to versions compatible with Next.js 14.
  2. Verify your tsconfig.json settings align with the new project structure and TypeScript requirements.