A CLI to compile an entire folder with StyleX #412

nmn · 2024-02-02T00:37:19Z

What changed / motivation ?

StyleX needs a bundler integration to work correctly. It also depends on Babel. However, this can be burden when trying to integrate into various projects built with project starters like Next.js, Solid Start and create-react-app. These projects have a complex bundler setup and it can be hard to integrate into them correctly. In some cases, like Next, the tooling may be written in Rust where an integration of the Babel plugin is impossible.

In order to provide a clean and reliable escape hatch for these scenarios, we should have a CLI that transforms an entire folder of JS files and outputs the resulting CSS file. (Tools like Tailwind and PandaCSS similarly side-step the built-in bundler because of how hard it is to integrate)

Expected Behaviour

For this example, consider a Next.js app configured to use the src/ folder with a src/app/ within that contains actual routes. When using the CLI, you'd be able to make another folder called, say, source/ and gitignore src/ folder. The source/ folder would contain all the same files that would normally be defined within the src/ folder, but you'd be able to use StyleX.

The CLI will then:

Transform every single JS file within the source/ folder with the StyleX Babel plugin and output it at the same relative path in the src/ folder.
While transforming it will collect the generated CSS for each file and output a CSS bundle at src/stylex-bundle.css.
The transformed JS files should be updated to include an import of the stylex-bundle.css file. (Configurable)

With this process, the StyleX CLI would run first and generate an src/ folder with your actual source code. After this, the usual next dev script will be able to take over and run as usual.

Additionally, the CLI should also:

Have a watch mode so that only the files that are edited are recompiled, and the generated CSS file is updated accordingly.
Can be configured to also pre-compile a given list of node_modules packages and write the compiled files in some locations.
- Any processed JS files that import these packages, should be updated to rewrite their imports to point to the compiled location.

Finally, there are a few requirements for the configuration (This is probably a lot of the work):

The basic configuration options should be possible with both CLI args and with a file config.
It should be possible to configure the StyleX Babel plugin without a .babelrc file at the project root. (Next goes into Babel mode if it detect a .babelrc file)
It should be possible to run additional Babel transforms in addition to the StyleX Babel plugin

Stretch Goals

Avoid recompiling unchanged files between runs (even without watch mode).

Possible tools that can be used:

fb-watchman is a node client for watchman. A tool that tracks file changes within a folder
chokidar
node-watch

necolas · 2024-02-02T01:15:17Z

Can be configured to also pre-compile a given list of node_modules packages

Note that this is kind of how the RN ecosystem (Expo) handles compiling RN packages for web, and it's pretty fragile because someone has to know a list of all dependencies and sub-dependencies that might be need processing. Probably a bit of a challenge to reliably do that automatically. Do you know if the other CLI-based projects have any alternatives, or does everything expect the developer to list out the packages to be processed?

nmn · 2024-02-02T06:56:57Z

I know that Next has a transpilePackages option to compile packages manually. I'm following their lead on this since this.

I understand that the node_modules processing is going to be a challenge. I avoided doing this for a while, but there are simply too many esoteric build setups where such a system will always be needed. It unblocks StyleX usage without a huge ecosystem of bundler and framework plugins.

github-actions · 2024-02-10T07:07:01Z

compressed-size: runtime library

Size change: 0.00 kB
Total size: 2.52 kB

View unchanged

Filename: gzip (minify)	kB size	kB change	% change
`./packages/stylex/lib/stylex.js`	1.04 (3.22)	0.00 (0.00)	0.0% (0.0%)
`./packages/stylex/lib/StyleXSheet.js`	1.48 (3.75)	0.00 (0.00)	0.0% (0.0%)

github-actions · 2024-02-10T07:09:48Z

compressed-size: e2e bundles

Size change: 0.00 kB
Total size: 1128.55 kB

View unchanged

Filename: gzip (minify)	kB size	kB change	% change
`./apps/rollup-example/.build/bundle.js`	1005.20 (10185.36)	0.00 (0.00)	0.0% (0.0%)
`./apps/rollup-example/.build/stylex.css`	123.34 (773.82)	0.00 (0.00)	0.0% (0.0%)

nmn · 2024-02-10T11:59:52Z

Converting to draft while it's progress. Mark it as ready for review, when it's ... ready for review.

Jta26 · 2024-02-14T22:06:48Z

This is ready for an initial review.

I have no idea how to make eslint ignore my test files that are transfomed by babel. I tried adding to the ignorePatterns in .eslintrc.js, but it doesn't seem to work. I'm open to ideas.

Jta26 · 2024-02-14T22:18:19Z

This is ready for an initial review.

I have no idea how to make eslint ignore my test files that are transfomed by babel. I tried adding to the ignorePatterns in .eslintrc.js, but it doesn't seem to work. I'm open to ideas.

I figured it out

shawngustaw · 2024-02-21T01:12:25Z

@nmn any word on when this will land? If this is close I don't mind using a beta version and testing it out if you push a release!

necolas · 2024-02-21T01:38:16Z

packages/cli/README.md

@@ -0,0 +1,257 @@
+# @stylexjs/stylex


Don't forget to replace this README

necolas · 2024-02-21T01:39:26Z

packages/cli/__tests__/__mocks__/snapshot/components/button.js

+var stylex = _interopRequireWildcard(require("@stylexjs/stylex"));
+var _otherStyles = _interopRequireDefault(require("./otherStyles"));
+var _npmStyles = _interopRequireDefault(require("./npmStyles"));
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }


I wonder if for the sake of making these snapshots more readable we can avoid the babel module interop code appearing here

Is this an option that can be passed into babel? These files are supposed to be the expected output of the CLI, so I think adding a specific option for tests degrades the integrity of the tests a bit.

Yes, this is an option that can be passed into Babel. We don't want any transform other than StyleX to run. So we probably just need to set babelrc: false to ensure that is the case.

necolas · 2024-02-21T01:40:52Z

packages/cli/__tests__/__mocks__/snapshot/pages/home.js

@@ -0,0 +1,40 @@
+'use strict';
+
+Object.defineProperty(exports, "__esModule", {


Are these files mock snapshots? Or snapshots that accidentally got saved in the mocks directory? (File path is __mocks__/snapshot)

These are files I created by manually running mocks/source through the CLI in order to use in my tests to validate the output.

necolas · 2024-02-21T01:42:25Z

packages/cli/src/index.js

+  chalk.green(`\n
+  ______   _             _         __   __
+  / ____| | |           | |        \\ \\ / /
+ | (___   | |_   _   _  | |   ___   \\ V / 
+  \\___ \\  | __| | | | | | |  / _ \\   > <  
+  ____) | | |_  | |_| | | | |  __/  / . \\ 
+ |_____/   \\__|  \\__, | |_|  \\___| /_/ \\_\\
+                  __/ |                   
+                 |___/                
+`),


This doesn't looks particularly readable

There's some escaped characters. I'll attach a screenshot of what it looks like in the CLI.

I thought it would add more flavor to the cli :)

If you feel like it gets in the way we can remove it obviously

necolas · 2024-02-21T01:42:46Z

packages/cli/src/options.js

+export default {
+  directory: {
+    alias: 'd',
+    describe: 'The directory to compile with Stylex',


Suggested change

describe: 'The directory to compile with Stylex',

describe: 'The directory to compile with StyleX',

nmn · 2024-02-21T05:45:20Z

Looks like a few improvements still need to be made. I'll try to do this on my end shortly.

…stable_moduleResolution

packages/cli/package.json

Use the `lib` folder, not the `src` folder for the output of the package.

packages/cli/package.json

Jta26 · 2024-03-12T23:56:19Z

Closing to open a new one because something is messed up with github

nmn assigned Jta26 Feb 2, 2024

facebook-github-bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Feb 2, 2024

vercel bot deployed to Preview February 10, 2024 07:05 View deployment

Jta26 force-pushed the feat/cli branch from d4c30a4 to d88b766 Compare February 10, 2024 10:06

vercel bot deployed to Preview February 10, 2024 10:10 View deployment

nmn marked this pull request as draft February 10, 2024 11:59

vercel bot had a problem deploying to Preview February 12, 2024 07:48 Failure

vercel bot deployed to Preview February 12, 2024 07:59 View deployment

vercel bot deployed to Preview February 13, 2024 04:36 View deployment

vercel bot deployed to Preview February 13, 2024 04:43 View deployment

vercel bot deployed to Preview February 14, 2024 21:27 View deployment

vercel bot deployed to Preview February 14, 2024 21:44 View deployment

Jta26 marked this pull request as ready for review February 14, 2024 22:06

vercel bot deployed to Preview February 14, 2024 22:09 View deployment

vercel bot deployed to Preview February 14, 2024 22:21 View deployment

necolas reviewed Feb 21, 2024

View reviewed changes

vercel bot deployed to Preview February 21, 2024 13:12 View deployment

Jta26 and others added 15 commits March 12, 2024 12:27

[cli] typos

277d2d4

[cli] cool ascii art

fee0a5e

[cli] change bin to lib directory

24dc9a5

[cli] ignore prettier, eslint in compiled test files

122ff51

Fix type errors in CLI and minor tweaks

20bf7b2

Add syntax plugins

025886d

[cli] handle top level dir edge case, clean up on compile failure, un…

d8d1ce8

…stable_moduleResolution

[cli] next swc example

95fe6e0

[cli] better ascii art

6a2488e

[cli] basic .stylex.json config file support

572a3c6

[cli] output all as .js, use mkdirp, use babel typescript plugin

222da1f

cli-example w/ next -> pure stylex compile example

424c5d0

fix package-lock

5f6e115

[cli] add test for basic cli command functionality

3ab538e

[cli] add cli commands to README

12fb859

Jta26 force-pushed the feat/cli branch from 4fe9351 to 12fb859 Compare March 12, 2024 19:28

vercel bot had a problem deploying to Preview March 12, 2024 19:30 Failure

[cli] updated package-lock

dc01708

vercel bot had a problem deploying to Preview March 12, 2024 20:13 Failure

nmn commented Mar 12, 2024

View reviewed changes

packages/cli/package.json Outdated Show resolved Hide resolved

Update packages/cli/package.json

23625ab

Use the `lib` folder, not the `src` folder for the output of the package.

vercel bot had a problem deploying to Preview March 12, 2024 20:38 Failure

nmn commented Mar 12, 2024

View reviewed changes

packages/cli/package.json Outdated Show resolved Hide resolved

Update packages/cli/package.json

c982d09

vercel bot had a problem deploying to Preview March 12, 2024 21:28 Failure

Jta26 closed this Mar 12, 2024

Jta26 mentioned this pull request Mar 12, 2024

A CLI to compile an entire folder with StyleX #491

Closed

10 tasks

nmn mentioned this pull request Apr 9, 2024

Feat/cli #528

Closed

10 tasks

Jta26 mentioned this pull request Apr 29, 2024

Feat/cli #561

Merged

10 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

A CLI to compile an entire folder with StyleX #412

A CLI to compile an entire folder with StyleX #412

nmn commented Feb 2, 2024 •

edited by Jta26

Loading

necolas commented Feb 2, 2024 •

edited

Loading

nmn commented Feb 2, 2024

github-actions bot commented Feb 10, 2024

github-actions bot commented Feb 10, 2024

nmn commented Feb 10, 2024

Jta26 commented Feb 14, 2024 •

edited

Loading

Jta26 commented Feb 14, 2024

shawngustaw commented Feb 21, 2024

necolas Feb 21, 2024

necolas Feb 21, 2024

Jta26 Feb 21, 2024

nmn Feb 21, 2024

necolas Feb 21, 2024 •

edited

Loading

Jta26 Feb 21, 2024

necolas Feb 21, 2024

Jta26 Feb 21, 2024

Jta26 Feb 24, 2024 •

edited

Loading

necolas Feb 21, 2024

nmn commented Feb 21, 2024

Jta26 commented Mar 12, 2024

		@@ -0,0 +1,40 @@
		'use strict';

		Object.defineProperty(exports, "__esModule", {

	describe: 'The directory to compile with Stylex',
	describe: 'The directory to compile with StyleX',

A CLI to compile an entire folder with StyleX #412

A CLI to compile an entire folder with StyleX #412

Conversation

nmn commented Feb 2, 2024 • edited by Jta26 Loading

What changed / motivation ?

Expected Behaviour

Stretch Goals

Possible tools that can be used:

necolas commented Feb 2, 2024 • edited Loading

nmn commented Feb 2, 2024

github-actions bot commented Feb 10, 2024

github-actions bot commented Feb 10, 2024

nmn commented Feb 10, 2024

Jta26 commented Feb 14, 2024 • edited Loading

Jta26 commented Feb 14, 2024

shawngustaw commented Feb 21, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

necolas Feb 21, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Jta26 Feb 24, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nmn commented Feb 21, 2024

Jta26 commented Mar 12, 2024

nmn commented Feb 2, 2024 •

edited by Jta26

Loading

necolas commented Feb 2, 2024 •

edited

Loading

Jta26 commented Feb 14, 2024 •

edited

Loading

necolas Feb 21, 2024 •

edited

Loading

Jta26 Feb 24, 2024 •

edited

Loading