Nuxt 4 Migration
Developer Guide

Change 01 — Most Important

The New app/ Directory

This is the biggest change in the whole migration. In Nuxt 4, all frontend code lives inside a folder called app/. This did not exist in Nuxt 3.

Here is how the folder structure changed:

Change 02

Path Aliases — ~ and ~~

Nuxt has shortcuts for import paths. These shortcuts changed in Nuxt 4 because of the new app/ folder.

import MyHelper from '~/utils/myHelper';
import { config } from '~/config/tile-mountain';

import MyHelper from '~/utils/myHelper';       // app/utils ✓
import { config } from '~~/config/tile-mountain'; // outside app/ ✓

Change 03

useAsyncData — Always Add deep: true

In Nuxt 4, useAsyncData and useLazyAsyncData store data in a "shallow" ref by default. This means Vue will not automatically notice when the data inside changes. To fix this, you must add { deep: true }.

const { data } = await useAsyncData(
  'my-data-key',
  () => useSdk().magento.getProduct()
);

const { data } = await useAsyncData(
  'my-data-key',
  () => useSdk().magento.getProduct(),
  { deep: true } // ← ALWAYS add this
);

Change 04

useSdk() Replaces useNuxtApp().$sdk

The old way to call Magento APIs used useNuxtApp().$sdk. In Nuxt 4, there is a cleaner composable called useSdk() that does the same job with less code.

const { $sdk } = useNuxtApp();

const { data } = await useAsyncData(
  'key',
  () => $sdk.magento.getProduct()
);

// No need to import — auto-available

const { data } = await useAsyncData(
  'key',
  () => useSdk().magento.getProduct(),
  { deep: true }
);

Change 05

import.meta Replaces process

Nuxt 3 used process.client and process.server to check where code is running. Nuxt 4 uses the modern standard: import.meta.client and import.meta.server.

if (process.client) {
  window.addEventListener('scroll', handler);
}
if (process.server) {
  // server-only code
}

if (import.meta.client) {
  window.addEventListener('scroll', handler);
}
if (import.meta.server) {
  // server-only code
}

Change 06

Server Route Imports

Files inside the server/ folder are separate from the app/ folder. If a server route needs to import a utility from server/utils/, it cannot use the ~ alias (which now points to app/).

You have two correct options for server route imports:

import { validateAdmin } from
  '../../../utils/adminAuth';
// Count the dots to reach server/utils/

import { validateAdmin } from
  '~~/server/utils/adminAuth';
// ~~ = apps/web/ (the root directory)

Change 07

TypeScript: Ref<T | undefined>

In Nuxt 3, useAsyncData returned data typed as Ref<T | null>. In Nuxt 4, the return type changed to Ref<T | undefined>. This can cause TypeScript errors in functions that receive this data as a parameter.

function setupWatcher(
  data: Ref<ProductData | null>
) { // ... }

function setupWatcher(
  data: Ref<ProductData | null | undefined>
) { // Add | undefined to fix TS error }

Change 08

consola — Named Import Only

consola is the logging library used in this project. In Nuxt 4, you must import it using a named import. The default import no longer works.

import consola from 'consola';

consola.log('Hello world');
consola.error('Something failed');

import { consola } from 'consola';
// Note the curly braces { }
consola.log('Hello world');
consola.error('Something failed');

Change 09

apiPath() — No Template Literals Inside

The apiPath() function accepts only fixed string values. You cannot use a variable or a template literal inside the function call itself. If you need to add a query string, build the full URL outside the function.

// ❌ Template literal inside apiPath()
const url = apiPath(
  `fetchProductData${queryString}`
);

// ✓ Build the URL outside apiPath()
const url =
  `${apiPath('fetchProductData')}${queryString}`;

Change 10

Trepanel → TileMountainAE Component Rename

All components that were in the Trepanel/ folder have been renamed to TileMountainAE/. The brand "Trepanel" is being retired and its products now appear on the Tile Mountain UAE website.

Change 11

Where to Put New Files

When you create a new file, this table will help you decide exactly where it should go.

Change 12

Developer Checklist

Use this checklist every time you write or change code. Go through each item before you push your changes.

• ☐
  Is the new file inside apps/web/app/?All frontend code (components, composables, pages, assets, plugins, utils) must be inside the app/ folder.
• ☐
  Are your imports using the correct alias?Use ~ for things inside app/ and ~~ for things outside app/ (config, server).
• ☐
  Did you add { deep: true } to useAsyncData and useLazyAsyncData?Without this, reactive updates to fetched data may not work correctly in Nuxt 4.
• ☐
  Are you using useSdk() instead of useNuxtApp().$sdk?The new composable is cleaner and auto-imported.
• ☐
  Have you replaced process.client / process.server?Use import.meta.client and import.meta.server instead.
• ☐
  If you're in a server route, are imports correct?Use relative paths or ~~ — never ~ for server utilities.
• ☐
  If a function accepts data from useAsyncData, does it accept | undefined?Update the TypeScript type to Ref<YourType | null | undefined> to avoid TS errors.
• ☐
  Are you importing consola as a named import?import { consola } from 'consola' — with the curly braces.
• ☐
  Are you looking for Trepanel components in the right place?All Trepanel components have moved to app/components/TileMountainAE/.
• ☐
  Did you run yarn lint before pushing?This checks TypeScript types too. Fix all errors before pushing your branch.

Change 13

Quick Reference

Keep this page open as a handy reference while you code.