This project contains the Ontario Design System Web Components and npm packages.
Web Components provide strong encapsulation for reusable components that can be integrated into web applications.
The Ontario Design System components are an implementation of the best practices of the Ontario Design System.
- Visit our Component Developer Documentation for more information about the npm packages and each available component.
- Visit our Ontario Design System Guidance for more information about the Ontario Design System, our best practices, and other design system features.
Stencil is a toolchain for building reusable, scalable Design Systems.
Learn more in the Stencil Docs.
Using Lerna, this project is made up of multiple packages that are linked together, called a monorepo. Lerna takes care of bootstrapping the packages within this repository together with their dependencies. It will install the node_modules for each package, then link the internal project packages together.
The fastest way to hit the ground running is to run,
pnpm install # Install the root packages
pnpm run refresh # Ready the project for developmentNote: The refresh script encompass cleaning, bootstrapping, and building of all the core Ontario Design System npm packages within the repository.
Firstly, Lerna needs to be installed at the root level of the project.
At the repository root run,
pnpm installThe ontario-design-system packages are all designed to be published as npm packages. In order to do any development, or to just build the project in general, the packages have to be built/updated before they can be used.
Simply run at the root of the repository,
pnpm run build-libsThis will build the packages that are marked as public and prep them for use with any app.
Checkout each package in the packages folder. They each have their own Readme and instructions on how to get started.
This project is made up of five packages.
Wanting to build and test within one of the framework applications? Running the build-libs script from the root triggers this behaviour.
The library can be built independently by running,
pnpm run buildContent coming soon.
Wanting to build and test within one of the framework applications? Running the build-libs script from the root triggers this behaviour.
The library can be built independently by running,
pnpm run buildThe ontario-design-system-component-library is the heart of the project, it contains each of the the custom web components. It uses the Stencil toolchain to allow for easy creation and compilation of custom components.
The build process of this library emits npm package compatible packages as well as component libraries for other JavaScript UI Frameworks.
Wanting to build and test within one of the framework applications? Running the build-libs script from the root triggers this behaviour.
The library can be built independently by running,
pnpm run buildThe project contains an HTML file called index.html that is immediately loaded when the development server is started it. It is a simple place to stage a component for development.
A development server can be run by running,
pnpm run startStencil CLI can generate a new component within the src/components folder. With the ontario-design-system-component-library being your current directory run,
stencil generate name-of-componentIf you don't have stencil installed globally, prefix the command with npx,
npx stencil generate name-of-componentThe ontario-design-system-component-library-react package is a React wrapper for custom web components generated by the ontario-design-system-component-library. It handles all the boilerplate code to wrap the components for import into any React app. Material emitted from the ontario-design-system-component-library build process is injected into this process every time there is a new build made within that package.
See the Stencil Docs on React for more information.
Note: This library doesn't currently support Next.js Server-Side Rendering. For now, use use client in wrappers around the components.
Wanting to build and test within one of the framework applications? Running the build-libs script from the root triggers this behaviour.
The library can be built independently by running,
pnpm run buildThe ontario-design-system-component-library-angular package is a Angular wrapper for custom web components generated by the ontario-design-system-component-library. It handles all the boilerplate code to wrap the components for import into any React app. Material emitted from the ontario-design-system-component-library build process is injected into this process every time there is a new build made within that package.
See the Stencil Docs on Angular for more information.
Wanting to build and test within one of the framework applications? Running the build-libs script from the root triggers this behaviour.
The library can be built independently by running,
pnpm run buildA React frontend to show off the whole process, from ontario-design-system-component-library components to React components. It is a simple Create React App application and demos the simplicity of using the generated components.
The application can be run in development by running,
pnpm run startThe application can be build for production by running,
pnpm run buildAn Angular frontend to show off the whole process, from ontario-design-system-component-library components to Angular components. It is a simple Angular application and demos the simplicity of using the generated components.
The application can be run in development by running,
pnpm run startThe application can be build for production by running,
pnpm run buildBuilt using Docusaurus, this package contains the React based documentation platform for easy deployment of the npm package and web components component documentation.
The documentation is sourced from the npm packages Readme files, as well as the Readme files of each component. To populate the documentation see the Quick Start section or each package section about building the package.
To update the documentation, simply rebuild the libraries and then re-run the development server.
The application can be run in development by running,
pnpm run startThis will start a development server that can be used to test out changes to the documentation.
The application can be build for production by running,
pnpm run buildEach package, as well as the root of the repository, contain package.json scripts to clean up each package/project.
The clean script is used to clean up any build artefacts that might be produced. It should not touch any installed dependencies and is good for making sure the builds build cleanly. Try this is you're running into any weird, non package related build issues.
In any project, or at the root of the repository run,
pnpm run cleanIf run at the root of the repository Lerna will execute each package's clean script, allowing the entire project to be cleaned up.
The clean:full script is used to clean any build artefacts as well as nuke the package's node_modules folder. For a non module clean see clean.
In any project, or at the root of the repository run,
pnpm run clean:fullIf run at root this will run the clean:full script on each package, which will clean build artefacts and nuke the node_modules directory. The root level node_modules directory will not be touched. This makes sure that Lerna is left around.
- Run all tests across the monorepo:
pnpm run test:e2e # Runs all e2e tests across monorepo
pnpm run test:unit # Runs all unit tests across monorepo- Dependency issues: Clear lockfile or
node_modulesif needed - Permission issues: Ensure PNPM is correctly installed and configured
- Build/test failures: Check logs for specific errors and verify that dependencies are correctly installed
Here are some helpful resources one can use to learn more.