stylesheets and javascript

STYLESHEETS AND JAVASCRIPT

How to work with CSS and JS within Fabricator Builder

Fabricator Builder comes with little opinion about how you should architect your Stylesheets and JavaScript. Each use case is different, so it's up to you to define what works best.

Resulting files

In the configuration, you can define the resulting files as keys, while their value is what will be in those files. This way, you can have one resulting file, or multiple ones, so you can split your toolkit into multiple features. It's not recommended to split a lot, so try to keep everything in on file, only split if you really need to.

Also, this way of defining the resulting files will let you specify testing styles and scripts, so you can test your materials in your toolkit before actually using them in your application. Each of them will be appended to the page.

If you have this configuration:

{
  "scripts": {
    "toolkit"     : "glob.to.your.toolkit.scripts",
    "toolkit-i18n": "glob.to.extra.files.enabling.i18n",
    "toolkit-test": "glob.to.scripts.for.testing.materials"
  },
  "styles": {
    "toolkit"     : "glob.to.your.toolkit.styles",
    "toolkit-test": "glob.to.styles.for.testing.materials"
  }
}

The following files will be created:

toolkit.js
toolkit-i18n.js
toolkit-test.js

toolkit.css
toolkit-test.css

As you can see, this enables us to test our materials and creating optional toolkit features.

Using TypeScript

When you want to use TypeScript instead of plain JavaScript, you'll have to make use of the webPack option, which includes a TypeScript loader. Also make sure you have a tsconfig.json file in your project root to avoid errors.

Creating a component library

When using TypeScript, and you want to publish your npm package to be consumed by others, you can let Fabricator Builder create the necessary component library files, so other projects can import components easily. Just include the following options in your Fabricator config file:

{
  "typescript": {
    "dest": "path.to.the.ts.lib.directory",
    "comp": "glob.to.your.ts.components"
  }
}

This will create all .js and .d.ts files needed to easily consume your components.

These files are only created when run in production mode!

In order to clarify the public API you want to expose, you can add a components.js and components.d.ts file to the root of your project, which look like this:

// components.js
// The public API of components to use.

exports.Component = require('./lib/other').Component;

// components.d.ts
// Let TypeScript know of public components.

export * from './lib/other';

This is not necessary, but it makes using your component library much easier.

Sass placeholders

Fabricator Builder has a feature, where all data from the toolkitConfig file will be used to fill in placeholders in your stylesheets. This is a great way to parameterize your toolkit in order to build different versions of it, or just make it easier to configure your toolkit and play with different options.

Placeholders like this:

/* key */

Will be replaced by this:

key: value !default;

The dot notation isn't supported, so only direct key-value pairs will be used for this. But you can always use objects to group your data, as they will also be accessible from your materials and templates.

Placeholders only work in your main sass file, not in includes, due to the way node-sass works.

Toolkit output structure

Fabricator Builder will output the following structure:

└─ dist
    ├─ assets
    │  ├─ fabricator
    │  │   ├─ icons
    │  │   ├─ images
    │  │   ├─ scripts
    │  │   └─ styles
    │  ├─ samples
    │  └─ toolkit
    │      ├─ fonts
    │      ├─ images
    │      ├─ scripts
    │      └─ styles
    └─ templates
    

This way, including your toolkit in your application will only requre the toolkit directory. Furthermore, you can work with your fonts and images with relative paths in your stylesheet.