This tool has been tested with small tests. It's now being tested on realistic patterns. Thanks for your patience
Feel free to reach out about which features you'd like prioritized for testing. For example, should I focus on dontFlatten: true vs false scenarios first? Understanding common use cases helps me test what matters most!
Welcome to AutoScope compiler for CSS, HTML and JavaScript (React is in the works)!
The aim of this tool:
- For team-wide adoption, eliminate all class collisions entirely.
- For private adoption, reduce collision problems.
Regardless of whether you write Vanilla classes or BEM.
When collisions are detected during compilation, AutoScope automatically adds a suffix to class names (either a short hash or a number, based on your config) — no manual renaming needed.
For example, if you write unscoped (Vanilla) classes like this:
<article class="recipe-card">
<h3 class="title">Chocolate Cake Recipe</h3>
<p class="desc">
This rich and moist chocolate cake is perfect for celebrations or just a
treat to satisfy your sweet tooth. Easy to bake and delicious to eat!
</p>
<ul class="ingredients">
<li>2 cups flour</li>
<li>1 ¾ cups sugar</li>
<li>¾ cup cocoa powder</li>
</ul>
<p class="instructions">
Preheat the oven to 350°F (175°C). Mix dry ingredients. Add eggs, milk, oil,
and vanilla. Beat well. Bake for 30-35 minutes.
</p>
</article>If dontFlatten is set to false, AutoScope will convert nested classes into a flat BEM-style structure, using the outer block name as a prefix.
<article class="recipe-card-2">
<h3 class="recipe-card-2__title">Chocolate Cake Recipe</h3>
<p class="recipe-card-2__desc">
This rich and moist chocolate cake is perfect for celebrations or just a
treat to satisfy your sweet tooth. Easy to bake and delicious to eat!
</p>
<ul class="recipe-card-2__ingredients">
<li>2 cups flour</li>
<li>1 ¾ cups sugar</li>
<li>¾ cup cocoa powder</li>
</ul>
<p class="recipe-card-2__instructions">
Preheat the oven to 350°F (175°C). Mix dry ingredients. Add eggs, milk, oil,
and vanilla. Beat well. Bake for 30-35 minutes.
</p>
</article>Suffix + flattening resolves the collision.
Likewise, if you write BEM with dontFlatten set to true, you can write:
<article class="recipe-card">
<h3 class="recipe-card__title">Chocolate Cake Recipe</h3>
<p class="recipe-card__desc">
This rich and moist chocolate cake is perfect for celebrations or just a
treat to satisfy your sweet tooth. Easy to bake and delicious to eat!
</p>
<ul class="recipe-card__ingredients">
<li>2 cups flour</li>
<li>1 ¾ cups sugar</li>
<li>¾ cup cocoa powder</li>
</ul>
<p class="recipe-card__instructions">
Preheat the oven to 350°F (175°C). Mix dry ingredients. Add eggs, milk, oil,
and vanilla. Beat well. Bake for 30-35 minutes.
</p>
</article>And if a collision is detected, it resolves again to
<article class="recipe-card-2"></article>or if set to hash:
<article class="recipe-card-c53df3"></article>Each CSS file in inputDir gets treated as its own scope. The filename is the scope name. Think of it as a block or module.
If your selectors do not start with the filename, the scope name will automatically be prepended to your selectors.
So instead of writing
.recipe-card {
}
.recipe-card .title {
}
.recipe-card .img {
}You can write
.recipe-card {
}
.title {
}
.img {
}Import your modules via:
<meta name="auto-scope" content="./css/recipe-card.css" />If there's 2 files with same name (same class name) in same HTML, you need to explicitly link them with the content.
<meta name="auto-scope-1" content="./css/product card/card.css" />
<meta name="auto-scope-2" content="./css/food card/card.css" />
<article class="card card--product" data-scope="1" />
<article class="card card--food" data-scope="2" />CSS files adjacent to your JavaScript will automatically be imported unless you include .exclude. in the file name.
Any function named getScopedHtml will be scoped.
function getScopedHtml() {
return `<article class="recipe-card"></article>`; //Scoping will be applied
}During compilation, your HTML and CSS will be uniquely scoped automatically, and the CSS and HTML converted to the scoped versions.
Starts dev mode, which watches your files in inputDir in realtime. Uses a sandbox environment folder dev-temp.
Build from inputDir to outputDir(or in private mode, to teamSrc)
In private mode, build regularly to commit significant changes. Your live edits only affect the temporary dev folder in dev mode, not the actual team repo.
Create a vite folder. Set your vite root to be this folder.
Set outputDir to vite.
use npx dev-vite and npx build-vite
Set up a Git repo for your private work (can be offline), and inside it, add the Git repo of your team's project.
Set teamGit to the project repo, and teamSrc to the folder/s that contains the source files of the project.
Before you begin your work, call this command. Important: this will download the team repo content back to your src on a new branch. The download will be class-based (.img), not type-based (img)
Stay up to date with the master branch by regularly calling this command. Your scoped work will be merged in a temporary folder called merge, which is where you have to resolve conflicts, if there are any for your scoped work.
When you're done and you've submitted your work and it has been merged successfully to the master branch, call this command to:
- Clean up temporary branches.
- Pull from master.
- If your personal repo is not online, just local, the working branch will be merged back into master.
In private mode, collisions can happen due to git not being synced up perfectly, or other people using a name you already used. When this happens, AutoScope will notify you about it, and that on next build, your suffix will be regenerated. I recommend building and committing this immediately with a clear message about rename.
npx add
npx commit
In private mode, your scopes need a hash for sync identification. It's applied only to the scope itself.
.recipe-card {
--scope-hash: xt2e34;
}
.recipe-card__title {
/*No hash*/
}<article class="recipe-card" data-scope-hash="xt2e34">
<h3 class="recipe-card__title">Chocolate Cake Recipe</h3>
</article>copyFiles in config is automatically set to teamGitrepo if left unset or set to true. You need the full content available relatively during development.
AutoScope has integrated support for:
- Prettier
- ESLint
- stylelint
- beautify
Install the package of the formatter/s you would like AutoScope to automatically apply everywhere.
In the config, set up formatters like so:
{
formatters: {
all: 'prettier';
}
}or
{
formatters: {
html: 'beautify',
css: 'prettier'
}
}or
{
formatters: {
css: ['prettier', 'stylelint'];
}
}For each formatter, set up the config (if needed) in the same formatters object:
prettierConfigeslintConfigstylelintConfigbeautifyConfig
npx install-auto-scope will install a default config, and mark dist and dev-temp folders on .gitignore.
| Option | Type | Default | Description |
|---|---|---|---|
inputDir |
string | 'src' |
The directory to compile from |
outputDir |
string | 'dist' |
The directory to compile to |
dontFlatten |
boolean | false |
Flatten nested classes into BEM-style names |
useNumbers |
boolean | true |
Use number suffixes instead of hashes |
dontHashFirst |
boolean | true |
Do not suffix the first occurence |
mergeCss |
string | false |
Merge all the CSS into one file |
teamGit |
string | false |
The git repo folder of the main project |
teamSrc |
string/array | false |
The src directories within the team git repo e.g.src |
copyFiles |
string/bool/arr | false |
Copy directory content to the output dir, as is |
globalCss |
glob/globs | `` | Files to exclude from scoping (for global styles) |
flattenCombis |
array/boolean | [] |
Flatten combinators, e.g. from > to _a_ |
overrideConfig |
object | {} |
Override configs for certain files. Key = glob, value = object |