@onderwijsin/nuxt_base_layer NPM

Base layer for Nuxt 3 apps from @onderwijsin

This repo contains the base layer for all Nuxt 3 apps developed by Stichting Onderwijs in, that need to interact with the backend app on admin.onderwijsloket.com. More on Nuxt Layers.

What's in this layer?

The layer contains base configuration, logic, UI components and utilities to enable a speedy development process, and too share defaults between different apps. It is possible to override some of the default configuration (either from nuxt.config.ts or by setting env vars). More on that below.

Modules included in this layer:

All modules are initiated and configured from this layer, but some modules require additional (app specific) config. See 'Usage Requirements'

What else?

Besides the stuff listed above, this layer also contains:

Runtime config
App meta
Router (rendering behavior is set from parent app)
Stores
Composables that work well with the included modules (such as useTracking() and usePwa())
Logic for colorMode (aka dark and light mode) and appTheme (aka onderwijsloket, voorbereiden, hulpvoordeklas etc). Please note that the actual theme styles are not included! (see usage requirements)
app.vue with some nice to haves for local development
default.vue and clean.vue layouts. The default layouts sets atrributes to <html>, handles online/offline state of the app and inits a privacy notice

Version control

This layer is still in active development, which means breaking changes will occur from time to time. Please check the changelog for more information on which version of this layer is best for your use case.

The current pre-release version is v0.1.16

We're also considering breaking this layer into different parts for better reusability. This would mean there would be three layers (or 1 layer and 2 modules):

Base (configuration and utilities)
UI (themes, components, logic and related composables)
Auth (components, composable with auth mutations, store, pages and rendering logic, middlewares)

Also, we're planning to integrate @nuxthq/ui in an upcoming version. All components that have been developed so far will be refactored, which will probably include breaking changes

Known issues

Stuff that nomally would have been a dev dependency, is added as an actual dependency in the layer (this is due to an internals bug in Nuxt Layers). All these dependencies should be added manually to devDependencies in package.json of the parent app
Because of some bugs in Nuxt Layers, there are issues with (alias) import paths, specifically imports paths of modules. There is a workaround by specifying Nitro aliasses in nuxt.config.ts (see usage requirements)

Usage requirements

Nuxt Layers is a feature that is still in active development by the Nuxt team (it's in a phase between 'experimental' and 'production ready'). This means there are still some bugs in the feature, but is usable in production with some workarounds. Follow the steps below to get up and running with this layer.

This layer requires nuxt ^3.4.3 and node ^16.19.1. We also recommend installing all vs code extention that the Nuxt Team recommends, along with Todo Tree.

Create a new Nuxt project by running npx nuxi init <project-name>
In your package.json, add the following lines:

{
  "engines": {
    "node": "16.19.1"
  },
  "scripts": {
    "analyze": "npx nuxi analyze [--log-level] [rootDir]",
    "lighthouse": "npx unlighthouse --site staging.voorbereiden.onderwijsloket.com --debug"
  },
  "devDependencies": {
    "@nuxt/devtools": "^0.4.6",
    "@nuxt/image-edge": "^1.0.0-27968280.9739e4d",
    "@nuxt/kit": "^3.5.0",
    "@nuxtjs/apollo": "^5.0.0-alpha.6",
    "@nuxtjs/color-mode": "^3.2.0",
    "@nuxtjs/fontaine": "^0.2.4",
    "@nuxtjs/plausible": "^0.2.1",
    "@nuxtjs/tailwindcss": "^6.6.8",
    "@onderwijsin/nuxt_base_layer": "^0.1.16",
    "@pinia-plugin-persistedstate/nuxt": "^1.1.1",
    "@types/node": "^18",
    "@vite-pwa/nuxt": "^0.0.7",
    "@vueuse/core": "^9.13.0",
    "@vueuse/nuxt": "^9.13.0",
    "autoprefixer": "^10.4.13",
    "cross-env": "^7.0.3",
    "cssnano": "^5.1.15",
    "nuxt": "3.4.3",
    "nuxt-delay-hydration": "^1.1.4",
    "nuxt-icon": "^0.3.2",
    "nuxt-seo-kit": "^1.3.4",
    "prettier": "^2.8.8",
    "tailwindcss-debug-screens": "^2.2.1",
    "tw-colors": "^1.2.6",
    "unlighthouse": "^0.5.1"
  },
  "dependencies": {
    "lodash": "^0.4.9", // Will be deprecated and replaced by vueuse/debounce in next version
  },
  "overrides": {
    "vue": "latest"
  }
}

Install packages with

npm i

Create a .env file with the following values

FRONT_END_DOMAIN=<url>                    (i.e. https://onderwijsloket.com)
PLAUSIBLE_DOMAIN=<domain>                 (i.e. onderwijsloket.com)
MODE=<Mode>                               (see ./types/config)
APP=<App>                                 (see ./types/config)

# Optional
PWA_START_PATH=/dashboard                 (use if PWA is enabled)
ENTRY_PATH_ON_LOGIN=/dashboard            (use if auth is enabled)
ENTRY_PATH_ON_AUTH_FAILURE=/contact       (use if auth is enabled)

Edit your nuxt.config.ts file by adding the following code

// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
    extends: [
        "@onderwijsin/nuxt_base_layer"
    ],

    alias: {
        'click-outside-vue3': require.resolve("click-outside-vue3"),
        'lodash/debounce': require.resolve("lodash/debounce"),
    },
    ssr: true,

    // For docs, see https://nuxt.com/docs/guide/concepts/rendering#route-rules
    routeRules: {
        // Add rendering rules for routes (SSR is default, except for auth routes which have ssr: false)
    }
    
})

Add a netlify.toml file in your project's root. We recommend using the following config

[[plugins]]
  # Installs the Lighthouse Build Plugin for all deploy contexts
  package = "@netlify/plugin-lighthouse"
  
  # optional, fails build when a category is below a threshold
  [plugins.inputs.thresholds]
    performance = 0.5
    accessibility = 0.5
    best-practices = 0.9
    seo = 0.5
    pwa = 0.7

  # optional, deploy the lighthouse report to a path under your site
  [plugins.inputs]
    output_path = "reports/lighthouse.html"

Overriding the default config

It is possible to override specific values by adding the following to your .env file

BASE_API=https://admin.onderwijsloket.com/api/graphql
BASE_REST=https://admin.onderwijsloket.com/api/rest
PWA_START_PATH=/

Some specific thing to note are:

(partly) overriding nuxt.congig or tailwind.config won't work.
The base layer is rendering server side by default. Override this by adding route rules in your nuxt.config.ts such as

routeRules: {
  // Client side rendering is default
  '/': { prerender: true },
  '/*': { prerender: true }
}

The layers uses Vite PWA for Nuxt, which includes a service worker. You might want to change how this service workers behaves... (there is currently no options to disable PWA altogether, this will be added in later version)

Developing this layer

add LAYER_DEV=true to your .env file
The main branch is used as the default, and up to date branch. You can add new branches to develop specific features
When a new layer version is ready for production, run npm version. Then run npm run release --tag=$latestVersion --notes="$releaseMessage" (or npm run prerelease with the same flags)

That's it! Happy coding 🙂

@nuxtjs/html-validator @pinia/nuxt click-outside-vue3 mitt vue-screen

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago

12 months ago