@cewald/nuxt-boilerplate-layer

This is a personal-preference boilerplate for Nuxt projects which can be implement as a Nuxt layer into a plain project. It has a bunch of features and is published as a NPM package.

Configs

You can set all configruations in your nuxt.config.ts over the boilerplate config-name. A full list of configurations, you can see in the module/index.ts of the main local module of the boilerplate-layer.

Features

Installed modules

• @nuxt/eslint
• @nuxtjs/fontaine
• @nuxtjs/google-fonts
• @nuxtjs/i18n (optional)
• @nuxt/image (optional)
• @chettapong/nuxt-lodash (nuxt-lodash isn't maintained anymore and not compatible with Nuxt 4)
• @pinia/nuxt
• nuxt-svgo

Optional modules

@nuxt/kit is not able to install modules anymore. Optional modules are installed as dependencies in the package-manager already, but you have to include them in the modules array of the nuxt.config.ts yourself.

Installed packages (peer-deps)

• dayjs
• storyblok-js-client (optional)
• zod
• @vueuse/core
• gemoji
• tailwindcss
• @cewald/eslint-config

Composables

• useScreen: TailwindCSS based media-query helper which uses the project TW config
• useDayJs: dayjs lib composable
• useHideWhileScrolling: hide elements while scrolling is in progress
• useLoadScript: helper to load and init external scripts
• useValidation: validate a set of refs using a zod schema
• useModalStore: store for modal-handling in combination with the ModalWrapper component
• useDataCompliance: composable to safe simple-data compliance values for compliance-dialogs
• useScroller: library to build accessible scroller components using scroll-snap-type

Components

• AccordionWrapper/AccordionItem: modular accordion component
• ModalWrapper: wrapper for a modal based on useModalStore store
• FormHoneypotInput: form-input for honey-pot-form validation

Utils

• randomBetween
• sample
• shuffle
• lazyloadPicture: lazyload picture elements using intersection-observer
• honeypot: Return honeypot field name for form antispam

Storyblok

There are a lot functionalities around the Storyblok API and javascript SDK.

Typescript types auto-generation and -import

This module can automatically generate types from the components of your Storyblok space using their management API, which you then can use in your project for typesafety. You'll have to supply your space-id and oAuth token using the configs or environment variables.

Components

• SbPictureComponent: A component to serve SbImage images as they are stored in Storyblok
• SbRichtextComponent: A component to serve SbRichtText content from Storyblok

Stores

• SbStoreFactory: A one-line factory for typed Storyblok stores in your project
• SbStoreUtilityFactory: The utility-factory that SbStoreFactory is using, in case you need a more granular implementation of your store

Composables

• useStoryblokApiStore: Pinia store for an initialized StoryblokClient
• useRichTextResolver: Tooling to resolve structured-data Storyblok strings into HTML
• useSbImage: Composable for image calculations based in Storyblok images
• useSbBridge: Load Storyblok bridge as composable for Storyblok editor

Utils

• getSbImageOrientation: get image orientation by Storyblok image object
• isRichTextEmpty: checks if a rich-text variable is possibly just an empty skeleton

Prerendering

If you are using prerendering for specific routes this module can automatically load content URLs of specific component-types from Storyblok and add them using addPrerenderRoutes.

Prerendering by build-hook

If you are using Netlify and want to automatically update your prerendered content, you can use a Storyblok web-hook to trigger a build using a Netlify build-hook. There are two config-params necessary for it: netlifyBuildHookUrl & netlifyBuildHookSecret. The netlifyBuildHookSecret is a random secret string to secure the URL from outside-calls and the netlifyBuildHookUrl is the URL of the Netlify build-hook we mentioned earlier. If you have configured those two params you can serve the /api/storyblok/webhook/[your-secret] endpoint as a webhook in Storyblok and a new build is triggered each time you save a story.

Installation

1. Just install the package using your package manager:

   npm i -D @cewald/nuxt-boilerplate-layer

2. Add the layer to your nuxt.config.ts:

   export default defineNuxtConfig({
     extends: ['@cewald/nuxt-boilerplate-layer'],
     boilerplate: {
       // custom configs ...
     },
     //...
   })

Troubleshooting

Use global types as root generic type parameters of defineProps

If you want to use global types as root generic type parameters of defineProps like defineProps<MyComponentProps> Vue is going to drop an exception like: ERROR Pre-transform error: [@vue/compiler-sfc] Unresolvable type reference or unsupported built-in utility type. This is a bug in Nuxt/Vue and made ticket in their tracker for it: https://github.com/nuxt/nuxt/issues/29757

Until it is solved, you can bypass this problem by using this syntax:

const { propType } = defineProps<{ propType: MyGlobalPropType }>()

Development

You can create a /playground folder, where you mount or checkout your project you want to test.

If you want to use it in devcontainer, uncomment the mount configuration in the .devcontainer/devcontainer.json file, replace the path you want to mount and rebuild your container.

In your target project you now have to replace the boilerplate-module path to ../.

Now run npm run dev and your playground-project is using the current nuxt-boilerplate.

License

This project is licensed under the GNU General Public License v3.0.