Creating new layers

Nuxt layers are used to encapsulate Ripple functionality, so it can easily be shared and reused across projects, see key concepts - layers for a conceptual overview of what layers are and how they are used within Ripple.

Creating a new layer

The Nuxt Ripple CLI provides a simple way to initialise new layers, to create a new layer just run the following command:

npx @dpc-sdp/nuxt-ripple-cli init layer [DIRECTORY] --name {NAME}

Where [DIRECTORY] is the location to output the layer scaffolding and {NAME} is the name of the new layer. This command will scaffold everything you need to get started developing a new layer.

Developing the layer

Once the layer has been created you can start working with it by running the command below from the new layers directory. This will start a development server and allow you to start working on the layer.

npm run dev

The playground folder contains the essentials to get a test Nuxt application up and running, it includes a app.config.js, nuxt.config.js and .env file. The nuxt.config.js includes a core set of layers used by Ripple to get a reference sdp site up and running, it also includes the new layer itself.

The playground folder is a fully functional Nuxt application and can be used to test the new layer in isolation.

The layers structure is almost identical to a normal Nuxt app, meaning you can utilise the same features and conventions as a standard Nuxt application. i.e. create a pages folder for new pages, create a components folder for new components, etc.

Other useful commands:

• npm run build to do a production build of the .preview application (for testing purposes)
• npm run lint to lint the layer code with eslint
• npm run test to run any unit tests with jest

Publishing the layer

Once the layer is ready to be published it can be published to npm or pushed to a remote git repository, GitHub, GitLab, and Bitbucket are supported. For more on publishing to npm see contributing packages to the npm registry.

Using the layer

Nuxt layers can be added to any Nuxt site by including the layer in the nuxt.config.js file under extends. If the layer is published to npm don't forget to npm install it first.

export default defineNuxtConfig({
  extends: [
    '@dpc-sdp/nuxt-ripple', // An npm installed package
    'github:dpc-sdp/ripple-vic-gov-au-custom#1.0.0' // A tagged git repository
  ]
})

Also, make sure to check the layers documentation for any additional configuration that may be required.

To extend from a private repository, you need to add a GIGET_AUTH=<token> environment variable, with an auth token from your git provider.

Caveats when using layers from a git repository

If a layer is added via a git repository and that layer has npm dependencies, you will need to manually install them within the Nuxt application utilising the layer. The Nuxt team are looking at auto-installing layer dependencies in the future, see issue #13367.

You will also need to alias the dependencies in the Nuxt application, so they can be resolved to the correct package location. This can be done by adding an alias object to the nuxt.config.js file.

export default defineNuxtConfig({
  alias: {
    'date-fns': require.resolve('date-fns')
  }
})