[Graphite MQ] Draft PR GROUP:spec_a01979 (PRs 20)

CONTRIBUTING.md

@@ -6,97 +6,83 @@ We want this community to be friendly and respectful to each other. Please follo
 
 ## Development workflow
 
+> [!IMPORTANT]  
+> Scripts in this project are designed to be run in a bash environment using [Yarn](https://yarnpkg.com/) and [Corepack](https://yarnpkg.com/corepack). If you are using a different shell, you may need to adjust the commands accordingly.
+
 This project is a monorepo managed using [Yarn workspaces](https://yarnpkg.com/features/workspaces). It contains the following packages:
 
 - The library package in the root directory.
 - An example app in the `example/` directory.
 
 To get started with the project, run `yarn` in the root directory to install the required dependencies for each package:
 
-```sh
-yarn init -2
-yarn
-yarn build
-```
-
+> [!NOTE]
+> If you do not have Yarn v3/4 installed, you can install it via [Corepack](https://yarnpkg.com/corepack) by running: `npm install -g corepack`
 > Since the project relies on Yarn workspaces, you cannot use [`npm`](https://github.com/npm/cli) for development.
 
-The [example app](/example/) demonstrates usage of the library.
-
-It is configured to use the local version of the library, so any changes you make to the library's source code will be reflected in the example app. Most changes to the library's code will be reflected in the example app without a rebuild, but changes to the Metro, Babel or compiler sections will require a rebuild.
-
-You can rebuild the library by running:
-
 ```sh
-yarn build
+yarn init -2     # We require Yarn 4
+yarn clean       # Install dependencies, rebuild the project and example app
+yarn example ios # Or yarn example android
 ```
 
-There is no rebuild watch command, as if you are changing code that requires a rebuild, you will also need to restart the example app server to observe any changes.
+Once the example app is built, you can use
 
 ```sh
-# Alias for yarn build && yarn example debug
-yarn build:debug
-
-# Alias for yarn build && yarn example start
-yarn build:start
-
-# Tips:
-
-## Quickly rebuild and refresh the simulator
-yarn build:debug --ios
-yarn build:debug --android
-yarn build:debug --web
+yarn example start       # Start Expo CLI
+yarn example start:build # Rebuild the project and start Expo CLI
+yarn example start:debug # Rebuild the project and start Expo CLI with debug logging
 ```
 
-### Building the example app
+## Example app
 
-The example app is built using a canary version of the Expo SDK, which requires a development build. Before running the example app on a device or simulator, you need to build the app using the following command:
-
-```sh
-yarn example expo prebuild
-
-yarn example ios
-# Or
-yarn example android
-```
-
-### Running the example app
+The [example app](/example/) demonstrates usage of the library.
 
-You can use various commands from the root directory to work with the project.
+It is configured to use the local version of the library, so any changes you make to the library's source code will be reflected in the example app. Most changes to the library's code will be reflected in the example app without a rebuild, but changes to the Metro, Babel or compiler sections will require a rebuild.
 
-To start the CLI:
+You can rebuild the library by running:
 
 ```sh
-yarn example start
+yarn build
 ```
 
-To start the CLI wih debugging enabled:
+**There is no rebuild watch command.** The example app should fast refresh with most code changes, but certain changes (like those to the Metro transformer or Babel plugin) will require a rebuild of the library and example app. For this reason, we recommend using the `start:*` commands to rebuild the library and start the example app server in one command.
 
 ```sh
-yarn example debug
+yarn example start       # Start Expo CLI
+yarn example start:build # Rebuild the project and start Expo CLI
+yarn example start:debug # Rebuild the project and start Expo CLI with debug logging
 ```
 
-To rebuild the example app on Android:
+The `yarn example start` commands are aliases for `expo start`. They accept the same arguments as `expo start`, so you can pass any Expo CLI options to them.
+
+For example, to open the example app on a specific platform, you can use:
 
 ```sh
-yarn example android
+yarn start --ios
+yarn start --android
+yarn start --web
+
+yarn start:build --ios
+yarn start:build --android
+yarn start:build --web
 ```
 
-To rebuild the example app on iOS:
+> [!TIP]  
+> `start:build` and `start:debug` will clear the cache before starting the Expo CLI. If you are experiencing issue with `yarn example start` not reflecting your changes, try running `yarn example start:build` or `yarn example start:debug`.
 
-```sh
-yarn example ios
-```
+### Rebuilding the example app
 
-To run the example app on Web:
+The example app is built using a canary version of the Expo SDK, which requires a development build. Before running the example app on a device or simulator, you need to build the app using the following command:
 
 ```sh
-yarn example web
+yarn example expo prebuild # Rerun the Expo prebuild command
+yarn example ios           # Or yarn example android
 ```
 
 ### Testing
 
-Remember to add tests for your change if possible. Run the unit tests by:
+Remember to add tests for your pull request if possible. Run the unit tests by:
 
 ```sh
 yarn test
@@ -110,7 +96,7 @@ yarn test
 Run the example via the command line with the `debug` script to enable debugging:
 
 ```sh
-yarn example debug
+yarn example start:debug
 ```
 
 This will print parsed CSS and style objects to the console, which can help you understand how the library processes CSS files.
@@ -163,7 +149,8 @@ yarn release
 
 The `package.json` file contains various scripts for common tasks:
 
-- `yarn`: setup project by installing dependencies.
+- `yarn`: install dependencies.
+- `yarn clean`: setup project by installing dependencies and rebuilding the project and example app
 - `yarn typecheck`: type-check files with TypeScript.
 - `yarn lint`: lint files with ESLint.
 - `yarn test`: run unit tests with Jest.
@@ -183,6 +170,10 @@ When you're sending a pull request:
 - Follow the pull request template when opening a pull request.
 - For pull requests that change the API or implementation, discuss with maintainers first by opening an issue.
 
+_Do not create pull requests for these reasons:_
+
+- Changing the scripts to work in non-bash environments
+
 ## Development notes
 
 ### Metro Transformer

README.md

@@ -172,6 +172,25 @@ export default function App() {
 
 See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
 
+To quickly get started with the project, you can run:
+
+```sh
+yarn init -2     # We require Yarn 4
+yarn clean       # Install dependencies, rebuild the project and example app
+yarn example ios # Or yarn example android
+```
+
+Once the example app is built, you can use
+
+```sh
+yarn example start       # Start Expo CLI
+yarn example start:build # Rebuild the project and start Expo CLI
+yarn example start:debug # Rebuild the project and start Expo CLI with debug logging
+```
+
+> [!TIP]  
+> `start:build` and `start:debug` will clear the cache before starting the Expo CLI. If you are experiencing issue with `yarn example start` not reflecting your changes, try running `yarn example start:build` or `yarn example start:debug`.
+
 ## License
 
 MIT

example/package.json

@@ -4,6 +4,7 @@
   "main": "index.js",
   "scripts": {
     "start": "expo start",
+    "build": "expo start --clear",
     "debug": "DEBUG='react-native-css:*' expo start --clear",
     "android": "expo run:android",
     "ios": "expo run:ios",
@@ -19,9 +20,9 @@
     "react": "19.1.0",
     "react-dom": "19.1.0",
     "react-native": "0.80.1",
-    "react-native-reanimated": "~4.0.0-nightly-20250720-bdf9f39ee",
+    "react-native-reanimated": "4.0.1",
     "react-native-web": "~0.20.0",
-    "react-native-worklets": "0.4.0-nightly-20250720-bdf9f39ee",
+    "react-native-worklets": "0.4.1",
     "react-refresh": "^0.17.0"
   },
   "devDependencies": {

package.json

@@ -72,17 +72,21 @@
     "configs"
   ],
   "scripts": {
-    "test": "NODE_OPTIONS=\"${NODE_OPTIONS:-} --experimental-vm-modules\" jest",
-    "lint": "eslint",
-    "typecheck": "tsc --noEmit",
     "build": "bob build",
-    "build:debug": "yarn build && yarn example debug",
-    "build:start": "yarn build && yarn example start",
-    "prepublishOnly": "bob build",
-    "prepare": "bob build",
+    "clean": "find . -name 'node_modules' -type d -prune -exec rm -rf '{}' +; yarn install --immutable --immutable-cache --check-cache; yarn build; yes | yarn example expo prebuild --clean",
+    "clean:android": "yarn clean && yarn example android",
+    "clean:ios": "yarn clean && yarn example ios",
     "example": "yarn workspace react-native-css-example",
+    "lint": "eslint",
+    "prepare": "bob build",
+    "prepublishOnly": "bob build",
     "release": "release-it",
-    "release:nightly": "release-it 3.0.0-nightly.\"$(git rev-parse --short HEAD)\" --npm.tag=beta"
+    "release:nightly": "release-it 3.0.0-nightly.\"$(git rev-parse --short HEAD)\" --npm.tag=beta",
+    "start": "yarn example start",
+    "start:build": "yarn build && yarn example build",
+    "start:debug": "yarn build && yarn example debug",
+    "test": "NODE_OPTIONS=\"${NODE_OPTIONS:-} --experimental-vm-modules\" jest",
+    "typecheck": "tsc --noEmit"
   },
   "keywords": [
     "react-native",
@@ -154,9 +158,9 @@
     "react": "19.1.0",
     "react-native": "0.80.1",
     "react-native-builder-bob": "^0.40.13",
-    "react-native-reanimated": "~4.0.0-nightly-20250720-bdf9f39ee",
+    "react-native-reanimated": "4.0.1",
     "react-native-safe-area-context": "5.4.0",
-    "react-native-worklets": "0.4.0-nightly-20250720-bdf9f39ee",
+    "react-native-worklets": "0.4.1",
     "react-refresh": "^0.17.0",
     "react-test-renderer": "^19.1.0",
     "release-it": "^19.0.4",

yarn.lock

@@ -10889,9 +10889,9 @@ __metadata:
     react-native: "npm:0.80.1"
     react-native-builder-bob: "npm:^0.40.13"
     react-native-monorepo-config: "npm:^0.1.9"
-    react-native-reanimated: "npm:~4.0.0-nightly-20250720-bdf9f39ee"
+    react-native-reanimated: "npm:4.0.1"
     react-native-web: "npm:~0.20.0"
-    react-native-worklets: "npm:0.4.0-nightly-20250720-bdf9f39ee"
+    react-native-worklets: "npm:0.4.1"
     react-refresh: "npm:^0.17.0"
   languageName: unknown
   linkType: soft
@@ -10933,9 +10933,9 @@ __metadata:
     react: "npm:19.1.0"
     react-native: "npm:0.80.1"
     react-native-builder-bob: "npm:^0.40.13"
-    react-native-reanimated: "npm:~4.0.0-nightly-20250720-bdf9f39ee"
+    react-native-reanimated: "npm:4.0.1"
     react-native-safe-area-context: "npm:5.4.0"
-    react-native-worklets: "npm:0.4.0-nightly-20250720-bdf9f39ee"
+    react-native-worklets: "npm:0.4.1"
     react-refresh: "npm:^0.17.0"
     react-test-renderer: "npm:^19.1.0"
     release-it: "npm:^19.0.4"
@@ -10980,18 +10980,18 @@ __metadata:
   languageName: node
   linkType: hard
 
-"react-native-reanimated@npm:~4.0.0-nightly-20250720-bdf9f39ee":
-  version: 4.0.0-nightly-20250720-bdf9f39ee
-  resolution: "react-native-reanimated@npm:4.0.0-nightly-20250720-bdf9f39ee"
+"react-native-reanimated@npm:4.0.1":
+  version: 4.0.1
+  resolution: "react-native-reanimated@npm:4.0.1"
   dependencies:
     react-native-is-edge-to-edge: "npm:^1.2.1"
     semver: "npm:7.7.2"
   peerDependencies:
     "@babel/core": ^7.0.0-0
     react: "*"
     react-native: "*"
-    react-native-worklets: 0.4.0-nightly-20250720-bdf9f39ee
-  checksum: 10c0/d6e83f94b575323efc41f1d8e64e2030328a22075767ef9f9e0350abcc3aa4aae57853c05151c10ed77a93d75e9a6a8bf2a98d2d204ede17f69c071f700a924e
+    react-native-worklets: ">=0.3.0"
+  checksum: 10c0/bbf9d715f0305a586181b34fab6cb81ca3f2f737314efb02c7ce4bbbced54da388c2ccc6730450fa6be8fce4083ff29fe990a9a9accf6e4f9f7d4f9cc2a742ab
   languageName: node
   linkType: hard
 
@@ -11024,9 +11024,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"react-native-worklets@npm:0.4.0-nightly-20250720-bdf9f39ee":
-  version: 0.4.0-nightly-20250720-bdf9f39ee
-  resolution: "react-native-worklets@npm:0.4.0-nightly-20250720-bdf9f39ee"
+"react-native-worklets@npm:0.4.1":
+  version: 0.4.1
+  resolution: "react-native-worklets@npm:0.4.1"
   dependencies:
     "@babel/plugin-transform-arrow-functions": "npm:^7.0.0-0"
     "@babel/plugin-transform-class-properties": "npm:^7.0.0-0"
@@ -11042,7 +11042,7 @@ __metadata:
     "@babel/core": ^7.0.0-0
     react: "*"
     react-native: "*"
-  checksum: 10c0/1760062310b9e298bce51c9f7a8f51011880a5d676feec2e5c4a0f2390725f749d9aa24228a7f9bd579ada2785db14572e0d31cbd53fcccf51a8207d78205b3c
+  checksum: 10c0/cd54b322ea7c205ea2ea540a7e24e3a3c3bea75b57c4fe7e3c3fb8f7840290b66d2dbad763cf3987234396f8d4f5bd304601d7cd4f7adbf637529fa573822572
   languageName: node
   linkType: hard