The quickest way to set up a new front-end project using with the Umbraco Component Library is to download and install the Storm frontend scaffold CLI.

The tool will give you the means to start creating HTML prototype pages using the components listed in this Storybook.

1. Install the Scaffold CLI

Open a terminal window on your local machine and run the following command:

npm i -g @stormid/scaffold-cli

This will download and install the tool so that it's available for you to use from any terminal window from now on.

This step only needs to be done once, or whenever you are working from a new machine.

Installing the CLI tool in this way does not tie it to a specific project, and makes it available to use on any new sites you make in the future.

2. Create a new prototype

Browse to the folder on your local machine where you would like to store your prototype and open a terminal window.

Run the following command:

scaffold <insert-your-project-name-here> --umbraco

For example, if your project name was "Lorem" you would run:

scaffold lorem --umbraco

This will run a few steps in the terminal, and may take a while.

It first creates a folder called 'lorem' in your current local directory.
It then downloads and un-packs the storm scaffold code into that folder
It runs an 'npm install' command so that the site will be ready for you to use once the CLI completes.
Finally, it downloads the Umbraco-library package from npm and installs that too. This is the step that will allow you to start using these components in your prototype.

At this point your project is ready to use.

3. Set up your styling

As part of the install process, a default SCSS file will have been made for you in the following folder:

/your-project/src/css/index.scss

This SCSS file contains imports to all of the stylesheets that are available to you as part of the library, and are named to match their corresponding component.

These are initially commented out, leaving you free to uncomment the ones you require as you work through your prototype.

It's important to note that the components have been set up to work with a specific set of variables and mixins. It's strongly recommended that if you're using any of the components, you should also un-comment all abstract and base stylesheets as well to avoid errors in compilation and to keep the layout consistent with the library.

4. Import the components

The components from the umbraco library can be used by importing them at the top of your prototype pages.

The only difference between them and other components within your project is that they are imported from your installed 'node_modules' folder using a specific path. For example, to import the Blockquote component, add this line to the top of your page:

import Blockquote from "@stormid/umbraco-library/src/templates/components/blockquote";

The component can then be used anywhere in your page layout like this:

<Blockquote quote="Lorem ipsum" author="Dolor sit amet"/>

Details of the specific import path and the available properties for each component can be found within this storybook, under the 'Front end code' section of the component's story.

5. Make them your own

The components in this library are meant to give you a starting point for your prototype, but it's expected that many of them will need skinned and/or adjusted to match your project's needs.

Customising the CSS

For small adjustments such as colours, font faces and font sizes, the best approach is to import the component's stylesheet from the library and then create and import your own stylesheet below to make the adjustments. For example, if you needed to alter the banner colours:

@import '~@stormid/umbraco-library/src/css/components/buttons';
@import './components/banner.scss';

Each component's story shows you an example of the rendered markup, giving you a guide to the classes you'll need to override.

Overriding in this way and still importing the original stylesheet means that your component will recieve any updates to styling that may come in future releases of the library. Your alterations will remain in tact as they are seperate from the imported styles.

If your styling adjustments are significant, you may want to consider removing the imported library SCSS file import entirely and create your own from scratch. This would remove any possibility of updates from the libary, but give you a completely blank starting point for your own styling.

Customising the markup

If you find that the markup in the components doesn't match the needs of the design, you can create your own JSX version of the component and import that instead.

Each component's story shows you a rendered version of the markup that the component generates. This can be used as a starting point for creating your own JSX component. Alternatively, if you'd like to access the JSX file itself, you can find this in the project's 'node_modules' folder under '@stormid/umbraco-library/src/templates/components'.

Be aware that customising the JSX is a technical JavaScript task. Please feel free to discuss this with the Frontend developer team.