Shilp Config File

The Structure

Below is the full shape of the config file. Almost everything is just nested objects.

shilp.config.jscopy to clipboard
const shilpConfig = {
	// scss config: dev environment + build time
  scss: {
		imports: "",
		options: (options) => { ... }
	},

  // Build & Output
  source: "" or [],
  purge: (options) => { ... },
  colorFormat: "oklch" or "rgb",
  transpile: (options) => { ... },

  // override default config: replaces objects completely
  values: { ... },
	valueResolvers: { ... },
  theme: (values) => { ... } or { ... },
	inlineTheme: { ... },
  properties: { ... },
  intents: { ... },
  components: { ... },
  mixins: { ... },

  // extend default config: adds / modifies root-level config (deep merge)
  extend: {
    values: { ... },
		valueResolvers: { ... },
    theme: (values, inBuiltTheme) => { ... } or { ... },
		inlineTheme: { ... },
    properties: { ... },
    intents: { ... },
    components: { ... },
    mixins: { ... }
  }
}

export default shilpConfig;

How Config File is Processed

The process is simple:

1. Load internal default config to root-level
2. Override internal default config with your root-level config if provided
3. Deep merge from shilpConfig.extend to root-level config
4. Freeze the final configuration
5. Start generating CSS

Root level keys replace defaults. extend keys merge into defaults.

Root Level

Override theme configcopy to clipboard
const shilpConfig = {
  source: "react",
  // other config

  theme: { ... },

  extend: {}
}

export default shilpConfig;

Extend

Inside extend, everything is deep merged with the root-level config or in other words adds / modifies part of the root-level config.

Extend theme configcopy to clipboard
const shilpConfig = {
  source: "react",
  // other config

  extend: {
    theme: { ... }
  }
}

export default shilpConfig;

In most cases, extend is safer. Use root-level replacement only when you want full control.

Core System Config

These define how Shilp CSS used to generates plain css.

At a high level:

SCSS Config

Controls how SCSS is processed during development and build time.

imports

A string of SCSS imports that are automatically included before processing.

Useful when your styles depend on shared SCSS.

For example: Mixins uses list module from SCSS so it is added (@use "sass:list";) to the imports internally by default.

options

A function that receives the SCSS compilation options.

const shilpConfig = {
	source: "react",

	scss: {
		imports: "...",
		options: (options) => { ... }
	}
};

export default shilpConfig;

Default options for SCSScopy to clipboard
const defaultOptions = {
	// No Shilp CSS default options, configured as of now
};

You can modify or replace the options before they are passed to SCSS.

If you don’t define scss.options config, defaultOptions are passed to SCSS.

See: SCSS compileString Options

Build & Output Config

After css is generated, these options optimizes it.

source

It defines which markup files are scanned for removing unused styles (purging).

By default, Shilp CSS recommends scanning build output folders for more accurate and efficient purging.

purge

A function that receives the final purge options for removing unused styles.

Default options for Purge CSScopy to clipboard
const defaultOptions = {
	content: ["./dist/**/*.{html,js}"], // as source is "react"
	css: [{ raw: css }], // css is raw styles string
	safelist: [],
	// keep below options false for now, more will be explained in `/docs/life-cycle/purging`
	variables: false,
	keyframes: false,
	fontFace: false,
};

You can modify or replace the options before they are passed to Purge CSS.

If you don’t define purge config, defaultOptions are passed to Purge CSS.

See: Purge CSS Options

colorFormat

Default value is "oklch".

All the colors authoring happens in OKLCH format irrespecitve of the value of this option.

Important Note For RGB Format

If you set colorFormat: "rgb", It will conflict with @supports rules that check for oklch support.

variables.csscopy to clipboard
@supports (color: oklch(0% 0 0)) {
	html,
	:host {
		/* gradient gamut */
		--grdnt-gmt: in oklch;
	}
}

If your project relies on @supports (color: oklch(...)) { ... } checks, keep the default colorFormat: "oklch".

transpile

A function that receives the final Lightning CSS options for styles optimization.

Default options for Lightning CSScopy to clipboard
const defaultOptions = {
	// `finalCSS` is after color format conversion with `colorFormat` option
	code: Buffer.from(finalCSS),
	minify: true,
	sourceMap: true,
	// DEFAULT_BROWSER_TARGET: since 2023-01-31
	targets: createCSSTargets(DEFAULT_BROWSER_TARGET),
	nonStandard: {
		deepSelectorCombinator: true, // vue, angular
	},
};

You can modify or replace the options before they are passed to Lightning CSS.

If you don’t define transpile config, defaultOptions are passed to Lightning CSS.

See: Lightning CSS Options

Development vs Build

While running in development (on your local machine):

1. Your .css files are read and processed
2. Plain CSS is generated
3. The result is served to the browser

This happens inside the development environment. It is simply build-time processing happening live.

During production build:

1. Your .css files are read and processed
2. Plain CSS is generated
3. Unused styles are removed (if enabled)
4. Final CSS is optimized
5. Static CSS file is emitted

Now, Deploy 🚀 and Rock 🤘🏻🪩.