Get started for developers

Learn how to install and use LBCamden Frontend in a project.

LBCamden Frontend is a bespoke frontend library which contains code samples and macros for all available components.

It is based on GOV.UK Frontend and contains both:

  • components from GOV.UK in their original form
  • bespoke or customised components specifically for LBCamden Frontend

LBCamden Frontend allows developers to create pages and applications that adhere to the Camden Council Design System.

Using LBCamden Frontend

There are 2 routes to using LBCamden Frontend, which you may apply depending on the type of integration you require.

For applications that support the Nunjucks library, macros are provided for each component which allow them to be used via templated functions. Each macro has defined parameters which allow values to be set within the component.

Macros have the advantage that should the underlying HTML of a component change, these changes are automatically applied when updating the bundled code. This is the preferred method of integrating the frontend library into an application.

If an application cannot use macros, we have also provided HTML code examples for each component. These examples can be copied into any integration, but it is the responsibility of the integrator to update them when changes to the frontend library are released and also implement additional logic to mirror the macro functionality.

LBCamden Frontend does not provide users with the complete functionality to create applications, and therefore it is the responsibility of the integration to adhere to the best practice and patterns documented in this design system. For example, make sure error messages are displayed correctly when validation fails, including links to fields which are invalid.

Getting started

Regardless of your integration route, we recommend you install the publicly available npm package into your project to implement LBCamden Frontend. The package contains all the files and macros required to implement LBCamden Frontend into an application, as well as tooling to extend and modify components and styles.

Alternatively, a precompiled version of LBCamden Frontend can be downloaded directly, and the bundled files added to your application.

Installing the package

These instructions assume you are familiar with using a command line interface and already have the latest LTS release of npm installed on your machine. LBCamden Frontend requires Dart Sass to be installed either within the project or globally. To use the macros within LBCamden Frontend, Nunjucks must also be installed.

Setting up a project

If you have already started your project without setting up an npm package, initialise one using:

npm init

Then install the LBCamden Frontend package:

npm i lbcamden-frontend

If you wish to integrate LBCamden Frontend using Nunjucks, you will also need to install GOV.UK Frontend via npm:

npm install govuk-frontend

Additionally, you can install the Dart Sass and Nunjucks packages if they are not already present within your project:

npm i sass nunjucks

Importing JavaScript modules

Some of the components in this library require supporting JavaScript to work fully. You have two options for importing it.

Using a bundler

If you are using a bundler such as Vite or Webpack, import and call the initAll functions from both the LBCamden and GOV.UK Frontend libraries. Make sure the script is loaded after all body content. Using type="module" on the script tag in the head will do this.

Using the pre-compiled JavaScript assets

If you do not have a JavaScript bundler in your build pipeline, you can import the prebuilt JavaScript bundle from LBCamden Frontend's dist directory. This will initialise both LBCamden and GOV.UK components automatically.

The pre-compiled library will add an LBCamden object to the window with a reinitialize() helper function. You may need to use this after page transitions in environments such as Liferay that re-fetch HTML fragments using JavaScript.

Using the pre-compiled asset files

Assuming your project has an assets directory, copy the contents of the dist directory to your asset directory:

cp ./node_modules/lbcamden-frontend/dist/* ./YOUR_PROJECT/ASSET_DIRECTORY/

Additionally, copy the supplied fonts and asset files into the root of your assets directory:

cp -r ./node_modules/lbcamden-frontend/dist/assets/fonts ./YOUR_PROJECT/ASSET_DIRECTORY
cp -r ./node_modules/lbcamden-frontend/dist/assets/images ./YOUR_PROJECT/ASSET_DIRECTORY

You can now implement LBCamden Frontend using the Core template. The bundled CSS expects assets to be served from the /assets path. If your project serves assets from a different path, define the $lbcamden-assets-path Sass variable before importing the Sass build.

Core template

The Core template contains the basic markup and structure required to adhere to the visual design of the Camden Council Design System. It contains the most basic configurations of the Header and Footer components, and an entry point for adding content.

It can be used as a starting point for working with components, or as a base template when integrating LBCamden Frontend into an application. The Core template can be found in the dist directory of the package and is called index.html. You may need to update it to reference the correct version of LBCamden Frontend you are using.

Working with HTML components

To implement the HTML version of a component, copy the code examples from either the Camden Council Design System documentation or the developer documentation. We recommend you do not change markup within a component and instead use targeted CSS rules to change its appearance where needed.

Components within the design system have been researched and thoroughly tested. Do not modify or recreate them with different markup. If you need to modify the HTML markup, consider the impact on functionality and accessibility.

Working with Nunjucks macros

If your application can support Nunjucks, for example an application developed using Express, we recommend integrating LBCamden Frontend using macros. This allows for a better developer experience, easier integration and seamless updates when non-breaking changes are released.

Add both node_modules/lbcamden-frontend/dist and node_modules/govuk-frontend/dist to your list of Nunjucks paths so Nunjucks knows where to find the templates and components.

You can then add {% extends "lbcamden/template.njk" %} to a template and use the defined block entry points within that file to add content and components via macros.

Staying up to date

Breaking changes are published as part of the release notes for each release.

LBCamden Frontend aims to follow semantic versioning, and implements MAJOR, MINOR and PATCH releases.

When implementing LBCamden Frontend into a project, we recommend having functional (for example Cypress) and visual regression (for example Chromatic) tests in place to make sure upstream changes do not impact downstream implementations.