Hello world!
12 |Something else
13 |No usage of fx so no pick up
14 | 15 | 16 | 17 | 18 | 19 | 20 |
13 | About the project
14 |
15 |
18 | 15 |
Hey
16 |ForgeCSS parses className strings as a small DSL and generates responsive CSS based on your own utility classes. It gives you Tailwind-like breakpoint expressiveness without adopting a new styling framework.
17 |Hey world!
6 |7 | I'm ForgeCSS. 8 |
9 | `, 10 | selected: true, 11 | type: "html" 12 | }, 13 | { 14 | filename: "styles.css", 15 | content: `.mt1 { margin-top: 1rem; } 16 | .mt2 { margin-top: 2rem; } 17 | .white { color: #fff; } 18 | .black-bg { background-color: #000; } 19 | .red { color: #9f0000; }`, 20 | selected: false, 21 | type: "css" 22 | }, 23 | { 24 | filename: "forgecss.config.json", 25 | content: `{ 26 | "breakpoints": { 27 | "d": "all and (min-width: 768px)" 28 | }, 29 | "bundleAll": true 30 | }`, 31 | selected: false, 32 | type: "javascript" 33 | } 34 | ]; 35 | export const ACTUAL_HTML_FILE = { 36 | filename: "page.html", 37 | content: "", 38 | selected: true, 39 | type: "html" 40 | }; 41 | export const TOTAL_CSS_FILE = { 42 | filename: "styles.css", 43 | content: "", 44 | selected: false, 45 | type: "css" 46 | }; 47 | export const DEFAULT_OUTPUT_FILES = [ACTUAL_HTML_FILE, TOTAL_CSS_FILE]; -------------------------------------------------------------------------------- /packages/forgecss/lib/usages.js: -------------------------------------------------------------------------------- 1 | let USAGES = {}; 2 | 3 | export async function findUsages(filePath, content, JSXParser) { 4 | try { 5 | if (USAGES[filePath]) { 6 | // already processed 7 | return; 8 | } 9 | USAGES[filePath] = []; 10 | const extension = filePath.split(".").pop().toLowerCase(); 11 | 12 | // HTML 13 | if (extension === "html") { 14 | extractClassNamesFromHTML(content).forEach((cls) => { 15 | USAGES[filePath].push(cls); 16 | }); 17 | return; 18 | } 19 | if (JSXParser && (extension === "jsx" || extension === "tsx")) { 20 | await JSXParser(content, USAGES, filePath); 21 | return; 22 | } 23 | } catch (err) { 24 | console.error(`forgecss: error processing file ${filePath.replace(process.cwd(), "")}`, err); 25 | } 26 | } 27 | export function invalidateUsageCache(filePath) { 28 | if (!filePath) { 29 | USAGES = {}; 30 | return; 31 | } 32 | if (USAGES[filePath]) { 33 | delete USAGES[filePath]; 34 | } 35 | } 36 | export function getUsages() { 37 | return USAGES; 38 | } 39 | 40 | function extractClassNamesFromHTML(html) { 41 | const result = []; 42 | const classAttrRE = /\bclass\s*=\s*(["'])(.*?)\1/gis; 43 | 44 | let match; 45 | while ((match = classAttrRE.exec(html))) { 46 | result.push(match[2].trim()); 47 | } 48 | 49 | return result; 50 | } -------------------------------------------------------------------------------- /examples/react/public/vite.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /packages/site/public/prism.css: -------------------------------------------------------------------------------- 1 | /* PrismJS 1.30.0 2 | https://prismjs.com/download#themes=prism-okaidia&languages=markup+css+clike+javascript+jsx+tsx+typescript */ 3 | code[class*=language-],pre[class*=language-]{color:#f8f8f2;background:0 0;text-shadow:0 1px rgba(0,0,0,.3);font-family:Consolas,Monaco,'Andale Mono','Ubuntu Mono',monospace;font-size:1em;text-align:left;white-space:pre;word-spacing:normal;word-break:normal;word-wrap:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;-moz-hyphens:none;-ms-hyphens:none;hyphens:none}pre[class*=language-]{padding:1em;margin:.5em 0;overflow:auto;border-radius:.3em}:not(pre)>code[class*=language-],pre[class*=language-]{background:#272822}:not(pre)>code[class*=language-]{padding:.1em;border-radius:.3em;white-space:normal}.token.cdata,.token.comment,.token.doctype,.token.prolog{color:#8292a2}.token.punctuation{color:#f8f8f2}.token.namespace{opacity:.7}.token.constant,.token.deleted,.token.property,.token.symbol,.token.tag{color:#f92672}.token.boolean,.token.number{color:#ae81ff}.token.attr-name,.token.builtin,.token.char,.token.inserted,.token.selector,.token.string{color:#a6e22e}.language-css .token.string,.style .token.string,.token.entity,.token.operator,.token.url,.token.variable{color:#f8f8f2}.token.atrule,.token.attr-value,.token.class-name,.token.function{color:#e6db74}.token.keyword{color:#66d9ef}.token.important,.token.regex{color:#fd971f}.token.bold,.token.important{font-weight:700}.token.italic{font-style:italic}.token.entity{cursor:help} 4 | -------------------------------------------------------------------------------- /packages/forgecss/tests/cases/01-usages/test.js: -------------------------------------------------------------------------------- 1 | import { JSXParser, readFileContent } from "../../../lib/helpers.js"; 2 | import { invalidateInventory } from "../../../lib/inventory.js"; 3 | import { findUsages, getUsages, invalidateUsageCache } from "../../../lib/usages.js"; 4 | import { getPath, expect } from "../../helpers.js"; 5 | 6 | export default async function test() { 7 | const cases = [ 8 | { 9 | file: getPath("/cases/01-usages/src/page.html"), 10 | expected: { 11 | [getPath("/cases/01-usages/src/page.html")]: [ 12 | "mt1 desktop:red", 13 | "fz3 mx-l [.dark &:hover]:red", 14 | "vibe" 15 | ] 16 | } 17 | }, 18 | { 19 | file: getPath("/cases/01-usages/src/page.tsx"), 20 | expected: { 21 | [getPath("/cases/01-usages/src/page.tsx")]: [ 22 | "a desktop:b", 23 | "c mobile:d desktop:b2 e", 24 | "a []:b []:c", 25 | "[&:hover]:a", 26 | "a [.dark &]:b c", 27 | "a [.dark desktop:b]:c d", 28 | "a [.dark &:has(.desc)]:c d", 29 | "a [.dark &[type='password']]:c d" 30 | ] 31 | } 32 | } 33 | ]; 34 | for (let i=0; i
13 | Back home
14 |
15 |
18 | 15 |
ForgeCSS introduces ForgeLang, a lightweight DSL embedded directly into your React className strings. It lets you express responsive design using intuitive prefixes like desktop:mt-4 or mobile:text-sm, then compiles those tokens into real CSS. Instead of reinventing a utility framework, ForgeCSS builds on top of the styles you already have—reading your existing CSS utilities, extracting their declarations, and generating fully scoped media-query variants automatically. This means your design system stays in control while ForgeCSS handles the heavy lifting of responsive expansion.
16 |The project was created for teams who love utility classes but want more expressive breakpoint logic without adopting a full Tailwind pipeline. By treating className as a parseable language rather than a plain string, ForgeCSS enables custom syntax, prefix extensions, and future transformations that can evolve with your codebase. It slots into any React project with minimal setup and produces predictable, deduplicated CSS output that mirrors your real styles. Think of it as a tiny compiler for responsive utilities—simple to adopt, endlessly flexible, and built for modern UI development.
17 |
95 |
96 |
97 | );
98 | };
99 |
--------------------------------------------------------------------------------
/packages/site/src/Syntax.tsx:
--------------------------------------------------------------------------------
1 | import fx from "forgecss/fx";
2 |
3 | const EXAMPLES = [
4 | {
5 | input: (
6 |
7 | foo bar
8 |
9 | ),
10 | outputHTML: foo bar,
11 | outputCSS: -,
12 | text: (
13 |
14 | foo and bar are just tokens here. No CSS is
15 | generated.
16 |
17 | )
18 | },
19 | {
20 | input: (
21 |
22 | hover:bar
23 |
24 | ),
25 | outputHTML: hover_bar,
26 | outputCSS: (
27 |
28 | hover_bar:hover {"{"} ... {"}"}
29 |
30 | ),
31 | text: (
32 |
33 | If hover is a valid pseudo class and bar is a
34 | valid utility, CSS will be generated for the hover state applying the styles set in{" "}
35 | bar class.
36 |
37 | )
38 | },
39 | {
40 | input: (
41 |
42 | desktop:bar
43 |
44 | ),
45 | outputHTML: desktop_bar,
46 | outputCSS: (
47 |
48 | @media (min-width: 780px) {"{"}
49 | 50 | 51 | desktop_bar {"{"} ... {"}"} 52 | 53 |
54 | {"}"} 55 | 56 | ), 57 | text: ( 58 | 59 | If
desktop is a valid breakpoint (defined into the ForgeCSS configuration) and bar is a
60 | valid utility, media query will be generated for the created class desktop_bar with the styles set in bar class.
61 |
62 | )
63 | }
64 | ];
65 |
66 | export default function Syntax() {
67 | return (
68 |
69 |
93 | );
94 | }
95 |
--------------------------------------------------------------------------------
/packages/forgecss/index.browser.js:
--------------------------------------------------------------------------------
1 | import {
2 | extractStyles,
3 | getStylesByClassName,
4 | invalidateInventory,
5 | resolveApplys,
6 | getInventory,
7 | getAllCSS
8 | } from "./lib/inventory.js";
9 | import { invalidateUsageCache, findUsages, getUsages } from "./lib/usages.js";
10 | import fx from './lib/fx.js'
11 | import { astToRules, rulesToCSS } from "./lib/forge-lang/Compiler.js";
12 | import { toAST } from "./lib/forge-lang/Parser.js";
13 | import { DEFAULT_OPTIONS } from "./lib/constants.js";
14 |
15 | function ForgeCSS(options) {
16 | const config = { ...DEFAULT_OPTIONS };
17 |
18 | config.breakpoints = Object.assign({}, DEFAULT_OPTIONS.breakpoints, options?.breakpoints ?? {});
19 | config.usageAttributes = options?.usageAttributes ?? DEFAULT_OPTIONS.usageAttributes;
20 | config.verbose = options?.verbose ?? DEFAULT_OPTIONS.verbose;
21 | config.minify = options?.minify ?? DEFAULT_OPTIONS.minify;
22 | config.bundleAll = options?.bundleAll ?? DEFAULT_OPTIONS.bundleAll;
23 |
24 | async function result() {
25 | try {
26 | const cache = {};
27 | const usages = getUsages();
28 | const ast = toAST(
29 | Object.values(usages).reduce((acc, i) => {
30 | return acc.concat(i);
31 | }, [])
32 | );
33 | let rules = astToRules(ast, {
34 | getStylesByClassName,
35 | cache,
36 | config
37 | });
38 | rules.push(resolveApplys());
39 | let css = rulesToCSS(rules.filter(Boolean), config);
40 | if (config.bundleAll) {
41 | css = getAllCSS() + "\n" + css;
42 | }
43 | if (config.minify) {
44 | css = minifyCSS(css);
45 | }
46 | if (config.verbose) {
47 | console.log("forgecss: output CSS generated successfully.");
48 | }
49 | return css;
50 | } catch (err) {
51 | console.error(`forgecss: error generating output CSS: ${err}`);
52 | }
53 | return null;
54 | }
55 |
56 | return {
57 | async parse({ css, html, jsx }) {
58 | if (!css) {
59 | throw new Error('forgecss: parse requires "css".');
60 | }
61 | if (!html && !jsx) {
62 | throw new Error('forgecss: parse requires "html" or "jsx".');
63 | }
64 | invalidateInventory();
65 | invalidateUsageCache();
66 | // filling the inventory
67 | try {
68 | extractStyles("styles.css", css);
69 | } catch (err) {
70 | console.error(`forgecss: error extracting styles.`, err);
71 | }
72 | // finding the usages
73 | try {
74 | if (html) {
75 | await findUsages("usage.html", html);
76 | } else if (jsx) {
77 | await findUsages("usage.jsx", jsx);
78 | }
79 | } catch (err) {
80 | console.error(`forgecss: error extracting usages.`, err);
81 | }
82 | return result();
83 | },
84 | fxAll: function (root) {
85 | const rootNode = root || document;
86 | const nodes = rootNode.querySelectorAll("[class]");
87 |
88 | for (let i = 0; i < nodes.length; i++) {
89 | let el = nodes[i];
90 | let original = el.getAttribute("class");
91 | if (!original) continue;
92 |
93 | let transformed = fx(original);
94 |
95 | if (typeof transformed === "string" && transformed !== original) {
96 | el.setAttribute("class", transformed);
97 | }
98 | }
99 | },
100 | fx,
101 | getUsages,
102 | getStylesByClassName,
103 | getInventory
104 | };
105 | }
106 |
107 | window.ForgeCSS = ForgeCSS;
--------------------------------------------------------------------------------
/packages/site/public/forgecss.svg:
--------------------------------------------------------------------------------
1 |
10 |
--------------------------------------------------------------------------------
/examples/react/src/App.tsx:
--------------------------------------------------------------------------------
1 | import { useState } from 'react'
2 | import './forgecss.css';
3 | import fx from '../../../packages/forgecss/fx'
4 |
5 | function App() {
6 | const [ progress, setProgress ] = useState(false);
7 | const [ success, setSuccess ] = useState(false);
8 | const [theme, setTheme ] = useState<'light' | 'dark'>('dark');
9 | const [errors, setErrors ] = useState<{ username: boolean | string, password: boolean | string }>({ username: false, password: false });
10 |
11 | async function submit(e) {
12 | e.preventDefault();
13 | setProgress(true);
14 | if (e.target.username.value === '') {
15 | setErrors(errors => ({ ...errors, username: 'Username is required' }));
16 | setProgress(false);
17 | return;
18 | }
19 | if (e.target.password.value === "") {
20 | setErrors((errors) => ({ ...errors, password: "Password is required" }));
21 | setProgress(false);
22 | return;
23 | }
24 | await new Promise((resolve) => setTimeout(resolve, 2000));
25 | setSuccess(true);
26 | setProgress(false);
27 | }
28 | function clearErrors(field: string) {
29 | setErrors((errors) => ({ ...errors, [field]: false }));
30 | }
31 |
32 | const isErrored = Boolean(errors.username || errors.password);
33 |
34 | return (
35 | syntax
70 | {EXAMPLES.map((example, i) => { 71 | return ( 72 |
73 |
90 | );
91 | })}
92 |
74 |
89 |
75 | {example.input}
76 |
77 |
78 |
88 |
79 | {example.outputHTML}
80 |
81 |
82 | {example.outputCSS}
83 |
84 |
85 | {example.text}
86 |
87 |
92 |
96 |
100 |
101 |
82 |
86 |
83 | 
84 |
85 |
84 |
89 |
140 |
90 |
119 | ForgeCSS is a compiler for utility CSS classes.
91 |
92 | ✔ Compiler that understands CSS class syntax
93 |
94 | ✔ It parses class strings, applies rules and structure, and compiles them
95 | into CSS.
96 |
98 | What it isn’t! 99 | 100 | ✖ Not a CSS framework or a transformer 101 | 102 | 103 | ✖ Not utility library 104 | 105 | 106 | ✖ Not a Tailwind plugin 107 | 108 | 109 | ✖ Not a runtime style engine 110 | 111 | 112 | ✖ Not a CSS-in-JS solution 113 | 114 |
115 |116 | ForgeCSS gives you the freedom to create your own utilities and compile them into CSS. 117 |
118 |
120 |
138 |
139 |
141 | 
147 |
148 |
147 | Test it out!
152 |
153 |
179 |
154 |
178 |
155 | updateInputFiles({ type: "selected", payload: i })} />
156 | updateInputFiles({ type: "change", payload: [selectedInput.filename, code] })}
161 | />
162 |
166 |
163 | 
164 |
165 |
164 |
167 | updateOutputFiles({ type: "selected", payload: i })} />
168 |
177 |
169 |
173 |
170 | {selectedOutput.content}
171 |
172 |
174 | 
175 |
176 |
175 | -
187 | {files.map((file, i) => {
188 | return (
189 |
- 190 | 191 | 192 | ); 193 | })} 194 |