Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/davesnx/styled-ppx/llms.txt

Use this file to discover all available pages before exploring further.

styled-ppx is authored and maintained by David Sancho. This page explains the origin of the project, why the approach works, and gives credit to everyone who made it possible.

​
Motivation — There was a need

Writing React with a CSS-in-JS library is one of the best combinations for building scalable design systems, UI libraries, and applications. When David first discovered Reason around 2018, there was no way to bind to styled-components or emotion — multiple threads in the community were asking for it, but no solution existed. During that period, bs-css and bs-emotion emerged as the main approaches to type-safe CSS in the ReasonML ecosystem. Both were thoughtful efforts, but they came with real drawbacks:
  • A new DSL on top of CSS. Simple properties were fine, but complex values became nearly unreadable. A straightforward width: calc(100% - 20px) in CSS had to be written as CSS.width(calc(min, percent(100.), px(20))) — in practice, most users reached for CSS.unsafe anyway.
  • A large runtime. The bundle size of bs-css starts at 64 kB and grows with usage, even with the dead-code elimination the compiler performs.
  • A questionable trade-off. Carrying a runtime just to write safe CSS felt like the wrong balance between safety and cost.
There had to be a better way.

​
It’s possible

Embedding CSS directly inside Reason/OCaml seemed like a bad idea at first. Most CSS-in-JS libraries that use native CSS syntax depend on JavaScript template literals — a feature that simply does not exist in OCaml. The key insight was discovering what a PPX actually is: a mechanism to embed other languages inside OCaml. A PPX runs before the compiler and rewrites extension nodes into ordinary OCaml code. That mechanism is a perfect analogue to JavaScript template literals for the purpose of embedding CSS. Embedding one language inside another is not a new idea — the most ubiquitous example is CSS inside HTML. Using real CSS syntax (rather than a DSL) unlocks integrations that are otherwise impossible:
  • Editor support — syntax highlighting, auto-complete, hover documentation.
  • Browser DevTools — inspect and live-edit styles in the familiar CSS panel.
  • Prototyping tools — copy/paste between Figma, Storybook, and source code without translation.
  • AI assistance — tools like GitHub Copilot understand CSS and can suggest completions inside styled-ppx annotations.
  • Designer legibility — teammates who know CSS but not ReScript can read and reason about styles directly.

​
It can be more powerful

Bringing type safety to CSS is a nice-to-have rather than a hard requirement, but styled-ppx takes it seriously. Because the PPX parses and validates every property/value pair at compile time, it functions as a full CSS compiler and type-checker embedded in your build. That foundation enables capabilities that go beyond what JavaScript CSS-in-JS libraries offer:
  • SASS-like features — nesting, pseudo-selectors, and at-rules handled at compile time.
  • Future CSS — new CSS features can be supported before browsers ship them.
  • Zero-runtime potential — because all styles are statically known at compile time, extracting CSS to static files at build time is a realistic future direction, eliminating the runtime injection cost entirely.
To understand the design in depth, watch the ReasonSTHLM Meetup talk where David walks through the motivation and architecture.

​
Credits

styled-ppx would not exist without the generosity of many people:

Javier Chávarri

Introduced David to Reason and shared deep knowledge of OCaml, ASTs, and PPX rewriters. Helped bootstrap the project from scratch.

Alessandro Strada

The project began as an evolution of bs-css-ppx. Alessandro’s work provided the initial inspiration.

Eduardo Rafael

Taught David how to write a compiler and type-checker. Authored the initial CSS value definition grammar and the parser combinator at the heart of styled-ppx.

Rizo

Contributed API design thinking, thoughtful discussions about styling philosophy, and deep conversations about the right abstractions for CSS in OCaml.

Max Lantas

Implemented the VSCode extension that brings CSS syntax highlighting to ReScript, Reason, and OCaml files.

Egor Chemohonenko

Implemented the vim-styled-ppx plugin, bringing the same editor experience to Vim users.
styled-ppx also builds on a long line of earlier work by the JavaScript community. The ideas, APIs, and tooling pioneered by styled-components, emotion, compiledcssinjs, linaria, and many others made this project conceivable.

Build docs developers (and LLMs) love

Get started for freeTalk to us