Use Fractal with your website

— 4 minute read

I have recently been using Fractal to build out component libraries for a couple of new projects and I was curious how it would integrate with a project website.

I needed a way to using the Fractal component library to integrate with a project website. I use Laravel and Laravel Mix as an elgant wrapper around Webpack for compiling my assets in both Fractal and projects. Here is what I came up with;

Setup your dependency permalink

When you setup your Fractal library, you will give it a name in the package.json. You will use this name attribute as your dependency name in your website project.

{
"name": "project-components"
}

The first step is to install your Fractal library as an Node dependency. Commonly you install packages from the public npm registry but there are other methods available. I host a lot of project code on GitHub, so I have used that method in my example.

Include your package as a dependency in your website project, with the key matching the name you setup in your Fractal package.json.

"dependencies": {
"project-components":
"git+https://github.com/company/components.git"
}

Now your website project has access to everything in the component library. In my case, I have SASS files and JS which need to be compiled before they could be used. You could use the asset management system in your website project to compile from these raw files, but I felt this wasn't the correct approach.

I wanted the component library to be the canonical version of the assets. To achieve this the component library would need to provide the compiled assets. As these files are generated, the don't belong in the version control. Luckily, you npm supports scripts for the different lifecycles of package management.

We can hook in to the install lifecycle script to build the assets when our package is installed. Update your component library package.json to include the script to build the production assets.

{
"name": "project-components",
"scripts": {
"production": "...",
"install": "npm run production"
}
}

Now when we install our component library in to our website project we have access to the compiled assets; the CSS, JS and any other files we want to use in production.


Using the assets permalink

Now we have access to the compiled assets from our component library, we need to bring them in to our website project. This article is focused on using Laravel Mix and the examples below are tailored to that build step. However, this will work with any build tools.

The simpliest solution is to copy the compiled folder, which I have setup as public, to your website project's public folder. Again, we need to reference the component library name to build the path to the files.

mix.copyDirectory('node_modules/project-components/public', 'public/')

This works, but you lose some of the benefits that Laravel Mix gives you, such as cache and cache busting. To make use of this, we can use the styles() and scripts() method to generate the correct mix-manifest.json file.

mix.styles('node_modules/project-components/public/css/site.css', 'public/css/site.css')

mix.scripts('node_modules/project-components/public/js/manifest.js', 'public/js/manifest.js')
mix.scripts('node_modules/project-components/public/js/vendor.js', 'public/js/vendor.js')
mix.scripts('node_modules/project-components/public/js/site.js', 'public/js/site.js')

mix.version()

Now you have a website project whose assets are in sync with the component library.

As long as your HTML matches the components, when a change is made to the component library, you can update your website project dependencies and the changes are reflected. All of this should work out of the box with any continuous integration tooling you are using to deploy your website project.