astroturf

Getting set up

astroturf is quick and easy to get going with. webpack is the tool of choice when it comes to astroturf, but we do have options if it's not your cup of tea.

Basic configuration

This is all the webpack setup necessary:

{
module: {
rules: [
{
test: /\.css$/,
use: ['style-loader', 'css-loader'],
},
{
test: /\.jsx?$/,
use: ['babel-loader', 'astroturf/loader'],
},
],
}
}

Simply add the astroturf/loader to the end of your JavaScript or TypeScript loader chain and you are ready to get compilin'!

If you want to use astroturf with a CSS preprocessor, just tweak an option to output the file type of your choice. Here's an example using Sass:

{
module: {
rules: [
{
test: /\.scss$/,
use: ['style-loader', 'css-loader', 'sass-loader'],
},
{
test: /\.jsx?$/,
use: [
'babel-loader',
{
loader: 'astroturf/loader',
options: { extension: '.module.scss' },
},
],
},
],
}
}

Becauase astroturf outputs CSS modules, it's best to use a .module.* extension. This automatically tells webpack's css-loader to process the stlyes correctly and expose the class names as exports for JS files. You can use whatever extension you like though, but may need to manually configure CSS modules elsewhere.

astroturf is right-sized for you and your needs. Quickly tweak behavior based on easy to use configuration options.

Options

Most options are available anywhere astroturf is used. Specify them via your webpack.config or babelrc depending on use and need.

  • extension: (default: '.module.css') the extension used for extracted style files. extension generally informs the flavor of CSS used (Sass, Less, etc) for the CLI or bundler to further process to plain css.

  • stylesheetTagName: (default: 'stylesheet') The tag identifier used to ' locate inline stylesheets declarations.

  • cssTagName: (default: 'css') The tag identifier used to locate inline css literals and extract them.

  • styledTagName: (default: 'styled') The tag identifier used to locate components.

  • enableCssProp: (default: true) compiles React.JS™ css component props to styled components.

  • enableDynamicInterpolations: (default: 'cssProp') enables or disables custom value interpolation, You can disable this feature if you need to target environments that do not support CSS custom properties.

  • experiments: Opt in to any experimental features we are testing out.

    • experiments.modularCssExternals: Set the css-modules flavor to modular-css which provides better inter-component referencing than the vanilla css-modules. requires css-module-loader to be configured

Configuration File

astroturf also supports configuration via localized configuration files. We recommend that dependencies using astroturf use this approach to avoid needing an single application-wide set of configuration options.

The supported file types are:

  • .astroturfrc
  • .astroturfrc.json

Both are assumed to JSON (with comments don't worry). You can also add configuration to the astroturf key in your package.json.

Other Tools

Use with Parcel

Add these lines to package.json to work with Parcel builder:

"postcss": {
"modules": true,
"plugins": [
"postcss-nested"
]
},
"babel": {
"plugins": [
"astroturf/plugin"
]
},

Use with Rollup

Add babel and postcss plugins to Rollup config file:

plugins: [
babel({
plugins: ['astroturf/plugin'],
}),
postcss({
extract: 'app.css',
modules: true,
plugins: [postcssNested],
}),
];

See example repl

Use with Gatsby

See gatsby-plugin-astroturf

Use with Preact

Add these lines to package.json to work with Preact:

"browser": {
"react": "preact"
},

Use with Next.js

See example

Use without webpack

If you aren't using webpack and still want to define styles inline, there is a babel preset for quickly configuring astroturf.

Config shown below with the default options.

// babelrc.js
module.exports = {
presets: [
[
'astroturf/preset',
{
cssTagName: 'css',
extension: '.module.css',
writeFiles: true, // Writes css files to disk using the result of `getFileName`
getFileName(hostFilePath, pluginsOptions) {
const basepath = join(
dirname(hostFilePath),
basename(hostFilePath, extname(hostFilePath)),
);
return `${basepath}__extracted_style${opts.extension}`;
},
},
],
],
};

The extracted styles are also available on the metadata object returned from babel.transform.

const { metadata } = babel.transformFile(myJsfile);
metadata['astroturf'].styles; // [{ path, value }]