Fuzzy Chainsaw is Connective DX's in-house toolset for making static websites and atomic styleguides. It's great for producing static web assets with an emphasis on atomic driven architecture.
To get started, download a copy of this repository from github.
Before you get up and running, make sure your environment has the following dependencies installed:
To install project dependencies, start up the best terminal on your machine and do:
npm install
Using Yarn instead
Yarn is an alterntive package manager that offers great performance and predictability. If you'd like to install dependencies using Yarn, do:
yarn
After you've installed npm depenedencies, FC provides command line scripts to automate usual tasks. Tasks are divided below into common workflows.
Use
npm runoryarn runto execute these commands in your favorite terminal.
Use these commands to develop a local copy of the website. These will watch for file changes and update bundles as you work.
| Command | Description |
|---|---|
dll |
Builds a DLL library of vendor files to speed up future builds. DLL Explanation |
dev |
Starts the development server and karama test runner in watch modes. |
build:dev |
Runs webpack-dev-server that watches for file changes. Starts a local sever at http://0.0.0.0:8080 (also accessible at http://localhost:8080) |
test:dev |
Runs the karma test runner in watch mode |
Use build commands if you want to quickly build a static representation of your website.
| Command | Description |
|---|---|
dll |
Builds a DLL library of vendor files to speed up future builds. DLL Explanation |
build |
Compiles source files into output directory |
test |
Runs the Karama test in single run mode |
start |
Starts a static server at http://localhost:8081 pointing at the output directory |
Use production commands to build a minimized static representation of the website.
| Command | Description |
|---|---|
dll:production |
Builds a production ready DLL library of vendor files. DLL Explanation |
build:production |
Compiles and minimizes source files into output directory |
production |
Runs dll:production and build:production tasks |
| Command | Description |
|---|---|
dll |
Builds a DLL library of vendor files to speed up future builds. DLL Explanation |
watch |
Compiles src directory to output directory and watches for file changes. |
dll:ci |
Builds a DLL library of only the vendor files required only for integration. |
build:ci |
Compiles only source files required for backend integration. |
dll:production:ci |
Builds a production ready DLL library of vendor files required only for integration. |
production:ci |
Compiles required assets to output directory – skips styleguide and html generation. |
Use these task to build a full copy of the website, including the DLL generation.
| Command | Description |
|---|---|
full:build |
runs dll and build tasks |
full:build:ci |
runs dll:ci and build:ci tasks |
full:production |
runs dll:production and build:production tasks |
full:production:ci |
runs dll:production:ci and build:production:ci tasks |
Scaffolding tasks are used to quickly create new atoms and molecules while developing a website.
| Command | Description |
|---|---|
new:atom [name] |
Creates a new atom component in the /source/atoms directory. |
new:molecule [name] |
Creates a molecule stateless integration molecule in the /source/molecules directory. |
new:organism [name] |
Creates a new stateless integration organism in the /source/organisms directory. |
DLLs are libraries of vendor files that are referenced by other tasks. This speeds up subsequent runs by referencing the DLL dependency tree instead of rebuilding it for every tasks. DLL files will only change when node_modules are update, and will be automatically generated after each npm install or yarn.
For most task this will be enough, but if you are building production ready code, be sure to use
dll:productionbefore running a production build tasks. Using the development DLL file in production, or visa-versa will result in hard to debug errors.
The BASE_URL defines the root path where the bundled files will be located. If you are uploading to a non-root path on a server (http://myserver.com/this-path/) this will need to be defined. This can be done on a one-off basis via build commands, or permanently via package.json.
If you are developing locally, or if your project will be served at the root of a domain or IP (http://myserver.com/ or http://133.713.37/), you don't have to worry about configuring the BASE_URL at all.
BASE_URL=/this-path/ npm run build
"baseUrl": "/this-path/",
Note: BASE_URL should always have a leading and trailing slash.
source/fc-config.js is used to configure the fuzzy chainsaw build tools. This is where you can define webpack bundles, dll bundles, and theme options.
By default FC is setup with a generic theme, but this can be removed or updated depending on if you need multibrand/multi-theme support.
We have tried to be thoughtful in our architectural decisions, and drive based on a few goals:
- Emphasize modular development
- Atomic based Architecture
- Reuseability between projects
- Reduce development friction
This might be subtitled, Unix Philosophy. The system should be composed of many smaller pieces that each have a single responsibility. This means making use of modules from NPM and developing our files using CommonJS module format.
We were inspired by the patterns in Brad Frost's Atomic Design. Our goal is to think about user interfaces as organisms of many small molecules and atoms. We've tried to build tools that help us think in this fashion.
Fuzzy Chainsaw projects are written using React JSX, which provides a great model for composing components and managing dependencies. Elements are split into three categories, Atoms, Molecules, Organisms. Atoms will be mostly generic small elements, where as molecules and organisms are collections of smaller elements.
Found in /source/elements/atoms
Atoms are small, reuseable elements that can be used in many contexts.
Found in /source/elements/molecules
Molecules are generally more singular purpose elements that are tied to a business requirement, or complex reusuable elmenets that require internal state.
Found in /source/elements/organisms
Organisms are specific arrangments of Atoms and Molecules with minimal styling requirements.
Found in /source/elements/modifiers
Modifiers are css styles and/or javascript containers that don't require specific html be defined.
Using work between projects has historically been a difficult nut to crack. We've selected technologies that have proven to be easily portable, and used an opionated folder and file naming scheme that self contains molecules.
Defining strong naming conventions help to ease the pain of context switching between projects. Instead of focusing on the naming style of your fellow developers, you can focus on the goals of their code.
All atoms and molecules share a similar set of files. Once you learn how one molecule is put together, you will have a very good idea how all molecule operate. Our preference is to repeat simple patterns many times instead of building fewer complex monolithic molecules.
The web development world is evolving rapidly. A tool that can automate the myriad tasks we regularly perform can redirect our focus on business decisions instead of trival tasks. We've provided a few different tools on your development adventures.
There are some very helpful command line scripts to help with development and continuous-integration. You can build a static set of files using npm run build or npm run production and create a local server to preview using npm run start. Use npm run dev if you are developing, this creates a server at http://localhost:8080 that updates as file changes.
Since you will likely be creating a number of atoms and molecules, there are also some commands to help with that common task.
npm run new:atom [Name]
npm run new:molecule [Name]
npm run new:organism [Name]
npm run new:stateful [Name]
Molecules come in a variety of shapes and sizes!
- Atoms are small, reuseable elements that can be used in many contexts.
- Molecules are generally more singular purpose elements that are tied to a business requirement, or complex reusuable elmenets that require internal state.
- Organisms are specific arrangments of Atoms and Molecules with minimal styling requirements.
- Stateful molecules are elements that require tracking of internal state properties. The scaffolding for Stateful molecule intends for a more application-based implementation of React.
You can read more on Stateless vs. Stateful molecules here
Remember that elements names use PascalCase
Connective DX’s front-end toolset.
Gulp is used as a general task runner. Web assets (html, js, css, images, svgs) are built with Webpack. React is used to rendering static html for CMS integration and render for browsers, using Babel to transpile ES6 to ES5. Enzyme is used to unit-test React components. PostCSS is used to transform CSS, with CSSNext as a base set of plugins. SVG Symbols are used to easily define and use vector icons.
It depends. It's a great tool for the way we build projects at Connective DX, but may not align with your project's goals. It is more focused on integrating with a back end system than application development.
It's a slow and steady trek to writing great documentation. We are doing our best, but we'd love your suggestions. If you'd like to help improve these documents, just create a new branch and submit a Pull Request – it's why we're on github! 💻 🎍
GitHub gifted it to us as the randomly generated suggestion and we took it, because it’s a pretty awesome phrase.
Fuzzy Chainsaw was developed to work best with Node's most recent LTS release and above. We intend to keep support pegged to Node's LTS schedule.
MIT Copyright (c) 2018 Connective DX