Legacy Ptchr Projects

A guide for migrating from legacy Ptchr Nuxt Statamic to the new Nuxt Statamic module.

Prerequisites

When using pnpm as your package manager, please add the following to your pnpm-workspace.yaml file:

pnpm-workspace.yaml

minimumReleaseAge: 1440 # 1 day
minimumReleaseAgeExclude:
  - "@nobears-front-end/nuxt-statamic"
  - "@nobears-front-end/nuxt-mapbox"
  - "@nobears-front-end/eslint"
  - "@nobears-front-end/utils"
  - "@nobears/ui"

Upgrade Nuxt

Upgrade Nuxt to the latest version

Upgrade Nuxt version to at least v4.1.0

npx nuxi@latest upgrade --dedupe

Update dir structure

Update the directory structure to the new Nuxt 4 structure.

Take a look at the Nuxt 4 directory structure for more information.

Update `nuxt.config.ts`

Remove srcDir, experimental and update any relative paths to the new directory structure.

nuxt.config.ts

export default defineNuxtConfig({
    // ...
    srcDir: 'src/',    experimental: {}    // ...
});

Be sure to remove old path references from tailwind.config.js

tailwind.config.js

module.exports = {
    content: [
        `./src/**/*.{vue,js,ts}`,        `./app/**/*.{vue,js,ts}`,    ],
};

Be sure to update the nuxt modules to the latest version that support Nuxt 4.

Among others:

@nuxt/eslint
@nuxt/fonts
@nuxt/image
@nuxt/icon
@nuxt/scripts
@nuxtjs/seo

Update I18n

Follow the I18n migration guide to update your I18n configuration.

And update your nuxt.config.ts file:

nuxt.config.ts

export default defineNuxtConfig({
    // ...
    i18n: {
        // ...
        langDir: "",        vueI18n: "",        restructureDir: true,    },
});

Update TypeScript

Follow the Nuxt 4 TypeScript migration guide to update your TypeScript configuration.

Remove the server/tsconfig.json file.

And update your tsconfig.json file:

tsconfig.json

{
    // ...
    "extends": "./.nuxt/tsconfig.json",    "files": [],    "references": [        { "path": "./.nuxt/tsconfig.app.json" },        { "path": "./.nuxt/tsconfig.server.json" },        { "path": "./.nuxt/tsconfig.shared.json" },        { "path": "./.nuxt/tsconfig.node.json" }    ]}

Remove `@unhead/vue`

pnpm remove @unhead/vue

Migrate `@nobears/statamic-nuxt-theme`

Update you `.npmrc`

Remove and add the following lines to your .npmrc file:

.npmrc

# @nobears/statamic-nuxt-theme (53506017)# @nobears/nuxt-statamic (52687963)# @nobears-front-end:registry=https://git.nobears.nl/api/v4/packages/npm/
//gitlab.com/api/v4/projects/53506017/packages/npm/:_authToken=${GITLAB_TOKEN}//gitlab.com/api/v4/projects/52687963/packages/npm/:_authToken=${GITLAB_TOKEN}//git.nobears.nl/:_authToken=${GIT_NOBEARS_TOKEN}

Remove the old `statamic-nuxt-theme` package

Run the following command to remove the old statamic-nuxt-theme package:

pnpm remove @nobears/statamic-nuxt-theme

Be sure to remove the extends configuration from your nuxt.config.ts file.

nuxt.config.ts

export default defineNuxtConfig({
    // ...
    extends: ['@nobears/statamic-nuxt-theme']     // ...
});

Install dependencies

By removing the statamic-nuxt-theme package, you will also remove some packages. You can install them again by running the following command:

pnpm add -D @nuxt/fonts @nuxt/icon @nuxt/image @nuxtjs/seo @nuxtjs/tailwindcss @tailwindcss/typography @gtm-support/vue-gtm @nobears/ui

And add them to your nuxt.config.ts file:

nuxt.config.ts

export default defineNuxtConfig({
    // ...
    modules: [
        '@nuxtjs/tailwindcss',        '@nuxt/fonts',        '@nuxtjs/seo',        '@nuxt/image',        '@nuxt/icon',        '@nobears/ui',    ],
});

Add the gtm support

Update your nuxt.config.ts file to add the gtm support:

nuxt.config.ts

export default defineNuxtConfig({
    // ...
    runtimeConfig: {
        public: {
            gtmId: process.env.NUXT_PUBLIC_GTM_ID,        }
    },
});

Create a new file app/plugins/gtm.client.ts and add the following code:

app/plugins/gtm.client.ts

import { createGtm } from '@gtm-support/vue-gtm'
export default defineNuxtPlugin((nuxtApp) => {
    const { gtmId } = useRuntimeConfig().public
    const siteConfig = useSiteConfig()
    if (siteConfig.env === 'staging' || siteConfig.env === 'production') {
      if(!gtmId) {
        console.error('No NUXT_PUBLIC_GTM_ID found in environment file.')
        return
      }
    }
    if(gtmId) {
      nuxtApp.vueApp.use(createGtm({
        id: gtmId,
        defer: true, // Speed up page load
        compatibility: false,
        enabled: true,
        debug: false,
        loadScript: true,
        vueRouter: useRouter(),
        trackOnNextTick: false,
      }))
    }
})

Add the following line to your .env.example file:

.env.example

NUXT_PUBLIC_GTM_ID=GTM-XXXXXXX

Update your `tailwind.config.js`

Add the missing @tailwindcss/typography plugin.

tailwind.config.js

module.exports = {
    // ...
    plugins: [
        require('@tailwindcss/typography'),    ],
};

Install the new `nuxt-statamic` module

Take a look at the installation guide to install the new nuxt-statamic module.

And update your nuxt.config.ts file:

nuxt.config.ts

export default defineNuxtConfig({
    // ...
    modules: [
        '@nobears-front-end/nuxt-statamic',    ],
    // ...
    statamic: {
        navigations: [
            // ...
            {
                handle: 'footer',
                fields: 'title,links',                fields: ['title', 'links'],            },
        ]

        // collections have been deprecated
        collections: [] 
        // sitemap is now part of the seo config option
        // (setting seo to true will automatically enable the sitemap)
        sitemap: true,        seo: true,    },
    // ...
    seo: {        redirectToCanonicalSiteUrl: true,    },});

Breaking changes

useStatamicPage

You will now need to use the useStatamicPageErrorHandler composable to handle the errors from the useStatamicPage composable.

pages/[...slug].vue

<script setup lang="ts">
const { data
, error
 } = await useStatamicPage
();
useStatamicPageErrorHandler
(error
);</script>

We simplified the API for the StatamicBlock component to make it easier to use. However, if you don't feel like updating your components, you can add the following to have the same functionality as before:

<template>
    <component
        :is="resolveComponent
(toPascalCase(block
.type))"
        v-for="block
 in data?.blocks"
        :
key
="block
.id"
        :
block
="block
"
    />

    <!-- Adding the background image for backwards compatibility can be done like so -->
    <component
        v-for="block
 in data?.blocks"
        :
key
="block
.id"
        :is="resolveComponent
(toPascalCase(block
.type))"
        :
block
="block
"
        :
style
="{
            backgroundImage
: block
.background_image?.permalink ? `url('${block
.background_image?.permalink}')` : undefined
,
            backgroundSize
: 'cover',
            backgroundRepeat
: 'no-repeat',
        }"
    />
</template>

<script lang="ts">
import type { StatamicBlockProps
, TextField
 } from "@nobears-front-end/nuxt-statamic";

export type TextImageProps
 = StatamicBlockProps
<{
    title
: TextField
;
    // ...
}>;
</script>

<script setup lang="ts">
const props
 = defineProps
<TextImageProps
>();
</script>

<template>
    <StatamicBlock :
block
="props
.block
">
        <!-- Content here -->
    </StatamicBlock>
</template>

Tailwind Configuration

For more information on how the spacing etc. is controlled, take a look at the Adding custom spacings section.

app/assets/css/main.css

@import "tailwindcss";
@import "@nobears-front-end/nuxt-statamic";
@theme {    --spacing-statamic-block-small--md: --spacing(20); /* Override the default spacing for the small block */}
@layer base {
    /* list the bg colors that are used in statamic blocks like so */
    [data-bg-color=''] {        background-color: var();    }}

Sitemaps

Sitemaps are used to help search engines index your website.

MVH Legacy

A guide for migrating from @maartenvanhunsel/nuxt-statamic module to the new Nuxt Statamic module.