How n1stre/rececss works
Project type and purpose
• This is an open-source, monorepo-style CSS utilities generator (rececss).
• It exposes a CLI, a core “engine,” framework-specific adapters (React, Vue, Vanilla), and a documentation website built with Next.js.
High-level file-structure analysis
• Root
• package.json (npm workspaces)
• .github/workflows (CI/CD)
• packages/rececss-core
• Implements core logic in Clean Architecture layers:
– 1_entities (Ruleset, Stylesheet)
– 2_usecases (BuildRulesets, GenerateStylesheetAssets)
– 3_adapters (StylesheetsController)
– 4_infrastructures (CLI entrypoint, config loader, FS & IO, CSS processor utilities)
• Exposes: CLI (npx rececss), programmatic API
• packages/rececss-components-* (react, vanilla, vue)
• Framework-specific wrappers that import rececss-core output and render live components
• packages/rececss-website
• Next.js app: docs and component previews
• Pulls in core and components packages via local deps, serves as end-user documentation and demo
Key README insights
• Customizable output (path, filename, splitByMedia)
• Rules, media queries, states, CSS generation pipelines
• Motivation: extendable, range support, custom pseudo-states
Diagramming the architecture
a. Main components
• CLI (rececss command)
• Core engine (UseCases + Entities + Adapters)
• Infrastructures:
– Config loader
– Filesystem/IO
– CSS Processor utilities
• Framework Adapters (React, Vue, Vanilla)
• Documentation site (Next.js)
• External: NPM registry, GitHub Actions (CI), end-users/projects
b. Relationships & data flow
• CLI → invokes Core UseCases (BuildRulesets, GenerateStylesheetAssets)
• Core UseCases → read config via Config loader (infra) → fetch rules definitions → produce CSS AST → write output via FS/IO (infra)
• Adapters (3_adapters) → expose programmatic API for other tools (e.g. component packages)
• Component packages → import core API → subscribe to generated CSS or call core at build time
• Website → imports core & components → fetches docs markdown → builds pages via Next.js → serves to browser
• CI workflows → build/test core, publish to NPM, deploy docs site
c. Architectural patterns & design principles
• Hexagonal/Clean architecture in rececss-core (layers: entities, usecases, adapters, infrastructures)
• Monorepo npm workspaces for shared deps & versioning
• Separation of concerns: core engine vs. UI/demo layers
d. Key technologies/frameworks
• Node.js, TypeScript, Jest (core tests)
• npm Workspaces / .npmignore / .np-config.json
• Next.js (docs site), React, Vue, Vanilla JS (component packages)
• GitHub Actions (CI), PurgeCSS recommendation
Be comprehensive but focused
• Four Clean Architecture layers in rececss-core
• How the monorepo structure supports multiple package outputs
• Data flow: config → generation → output → consumption by downstream packages/site
• Avoid over-splitting: group related adapters or infra blocks but call out key pieces (CLI vs. Config vs. FS)