facebook / facebook/stylex

[docs] Add a CSS Modules to StyleX migration playbook

Open
#1,810 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
JavaScript
Stars
10.3k
Forks
481
Avg merge
3d 8h
Merged PRs (30d)
13

Description

### Describe the feature request

In [discussion #1342](https://github.com/facebook/stylex/discussions/1342), Canva raised a concrete need for a safe, incremental way to migrate a large CSS Modules codebase to StyleX. A big-bang migration is not practical at that scale, and cases involving CSS precedence, complex selectors, and parent-supplied `className` values need particular care.

I would like to propose a self-contained Markdown migration playbook at:

`packages/docs/static/llm/stylex-migration-css-modules.md`

The guide provides a conservative workflow for inventorying CSS Modules, converting behavior that can be preserved safely, retaining unsupported CSS with clear reasons, and verifying the result. It is written for coding agents but is also usable as a human migration reference.

I have a v1 implementation ready and can open a PR for review. The initial scope is CSS Modules only; other styling systems can be handled separately later.

Thanks to @mellyeliu for setting up this opportunity to explore a practical migration path.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.