Create @stlite/react and import it from @stlite/browser (#1696)

* Create @stlite/react and import it from @stlite/browser

* Fix eslint.config.mjs

* Make @stlite/browser use @stlite/react

* Make @stlite/sharing use @stlite/react

* Fix @stlite/react

* Fix @stlite/sharing

* Make @stlite/desktop use @stlite/react

* Build vite-plugin to isolate the dependencies

* fix Makefile

* Add separate vitest.config.ts

* Rename StreamlitApp -> StliteApp

* Encapsulate toast callbacks into StliteAppWithToast and make browser/desktop/sharing use it

* Fix root tsconfig.json

* Move toastify components into @stlite/react and remove common-react

* Export stlite.css from @stlite/react and import it in browser/desktop/sharing

* Explicitly pass the wheel urls

* Make browser/desktop/sharing independent from @stlite/kernel

* Update react make rule

* Fix browser

* Set workerType

* Set kernel exports and update electron tsconfig

* Remove worker config

* Configure react/.prettierignore

* Fix

* Set assetFileNames in react/vite-plugin and update vite configs

* Separate @stlite/react/wheels for tree shaking

* Update AGENTS.md

* Fix

* Experimentally introduce vite-plugin-lib-assets to @stlite/react

* Emit wasm files separately

* fix react/vite.config.ts

* Add CI/CD pipeline for react package

* fix

* Fix dependencies

* Fix

* fix

* Fix react/.gitignore

* Set files field in react/package.json

* Add changeset

* Add react/README.md

* Fix dev server setting in react/vite.config.ts

* fix

* fix

* Mount ToastContainer

* fix

* comment

* Update .github/workflows/postbuild.yml

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Fix dep

* Remove define in react/vite.config.ts because process.env is ignored in lib build: https://github.com/vitejs/vite/blob/ab0c3b26533ebe48c9db3f7238938cec665f64ef/packages/vite/src/node/plugins/define.ts#L19

* Remove process.env.NODE_ENV definition from vite-plugin-stlite-react

* Fix wheel URL import utility

* Rename packages/react/src/wheels.ts -> packages/react/src/vite-utils/wheels.ts

* Stop using path.join to construct the assetFileName pattern because its path separator is OS-dependent

* Instantiate worker from data url directly

* Update react/README.md

* fix

* fix

* Run smoke test on @stlite/react

* Make test-react runnable

* Set kernel's development exports

* fix

* Return a new object instead of mutating a passed object in vite-plugin

* tmp: skip test react

* Add changeset

* Add dependencies of testing-library/react

* Run react test

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: whitphx

.changeset/flat-doodles-tap.md

@@ -0,0 +1,5 @@
+---
+"@stlite/kernel": minor
+---
+
+Add ESM exports, `worker` and `worker-runtime`

.changeset/grumpy-ducks-cross.md

@@ -0,0 +1,5 @@
+---
+"@stlite/react": minor
+---
+
+Create @stlite/react package that provides Stlite as React components

.changeset/modern-rabbits-vanish.md

@@ -0,0 +1,7 @@
+---
+"@stlite/browser": minor
+"@stlite/desktop": minor
+"@stlite/sharing": minor
+---
+
+Use @stlite/react as the foundation instead of depending on @stlite/kernel directly

.changeset/slick-lions-wave.md

@@ -0,0 +1,5 @@
+---
+"@stlite/browser": minor
+---
+
+Remove `workerType` option from `mount()`

.github/workflows/postbuild.yml

@@ -55,6 +55,7 @@ jobs:
     runs-on: ubuntu-latest
     outputs:
       browser: ${{ steps.parse-packages.outputs.browser }}
+      react: ${{ steps.parse-packages.outputs.react }}
       desktop: ${{ steps.parse-packages.outputs.desktop }}
     steps:
       - name: Download published packages info
@@ -72,12 +73,15 @@ jobs:
           PACKAGES=$(cat changesets-published-packages)
           if [ -z "$PACKAGES" ] || [ "$PACKAGES" = "[]" ]; then
             echo "browser=" >> $GITHUB_OUTPUT
+            echo "react=" >> $GITHUB_OUTPUT
             echo "desktop=" >> $GITHUB_OUTPUT
           else
             BROWSER_VERSION=$(echo "$PACKAGES" | jq -r '.[] | select(.name == "@stlite/browser") | .version // ""')
+            REACT_VERSION=$(echo "$PACKAGES" | jq -r '.[] | select(.name == "@stlite/react") | .version // ""')
             DESKTOP_VERSION=$(echo "$PACKAGES" | jq -r '.[] | select(.name == "@stlite/desktop") | .version // ""')
 
             echo "browser=$BROWSER_VERSION" >> $GITHUB_OUTPUT
+            echo "react=$REACT_VERSION" >> $GITHUB_OUTPUT
             echo "desktop=$DESKTOP_VERSION" >> $GITHUB_OUTPUT
           fi
 
@@ -142,6 +146,7 @@ jobs:
 
             const labels = {
               "visualizer-browser": "@stlite/browser",
+              "visualizer-react": "@stlite/react",
               "visualizer-sharing": "@stlite/sharing",
               "visualizer-sharing-editor": "@stlite/sharing-editor",
               "visualizer-desktop": "@stlite/desktop",
@@ -516,6 +521,95 @@ jobs:
             `
             });
 
+  deploy-react-preview:
+    needs: [get-build-info]
+    if: ${{ needs.get-build-info.result == 'success' && ( needs.get-build-info.outputs.pr-number != '' || success() ) }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      deployments: write
+    name: Deploy @stlite/react to Cloudflare Pages for preview
+    outputs:
+      url: ${{ steps.deploy.outputs.deployment-url }}
+      valid: 'true'
+    steps:
+    # Checkout for local actions (`uses ./*`).
+    - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+      with:
+        persist-credentials: false
+        sparse-checkout: .github
+        sparse-checkout-cone-mode: false
+
+    - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+      with:
+        name: stlite-react
+        path: ${{ runner.temp }}/artifacts/react
+        run-id: ${{ github.event.workflow_run.id }}
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Verify artifact contents
+      uses: ./.github/actions/verify-only-file
+      with:
+        directory: ${{ runner.temp }}/artifacts/react
+        filename: package.tgz
+
+    - name: Verify artifact attestation
+      uses: ./.github/actions/verify-artifact-attestation
+      with:
+        filepath: ${{ runner.temp }}/artifacts/react/package.tgz
+        expected-workflow-file: .github/workflows/test-build.yml
+        expected-ref: ${{ needs.get-build-info.outputs.pr-number && format('refs/pull/{0}/merge', needs.get-build-info.outputs.pr-number) || format('refs/heads/{0}', needs.get-build-info.outputs.branch) }}
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    - run: tar xzvf package.tgz
+      working-directory: ${{ runner.temp }}/artifacts/react
+
+    - name: Deploy
+      uses: cloudflare/wrangler-action@da0e0dfe58b7a431659754fdf3f186c529afbe65 # v3.14.1
+      id: deploy
+      with:
+        apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        command: |
+          pages deploy ${{ runner.temp }}/artifacts/react/package/build --project-name=stlite-react-preview --branch=${{ needs.get-build-info.outputs.branch }} --commit-hash=${{ needs.get-build-info.outputs.trigger-sha }}
+        gitHubToken: ${{ secrets.GITHUB_TOKEN }}
+
+  notify-react-preview-deployments:
+    needs: [get-build-info, deploy-react-preview]
+    if: ${{ needs.get-build-info.outputs.pr-number != '' && always() }}
+
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+
+    steps:
+      - name: Comment on PR
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        env:
+          PR_NUMBER: ${{ needs.get-build-info.outputs.pr-number }}
+        with:
+          script: |
+            const prNumber = process.env.PR_NUMBER;
+            const previewUrl = '${{ needs.deploy-react-preview.outputs.url }}';
+            const logUrl = 'https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}';
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+              body: `Deployment completed successfully ([log](${logUrl})).
+
+            Importable URLs:
+            - \`${previewUrl}/stlite.js\`
+            - \`${previewUrl}/stlite.css\`
+
+            \`\`\`tsx
+            import { StliteApp, createKernel } from "${previewUrl}/stlite.js";
+            import "${previewUrl}/stlite.css";
+            \`\`\`
+            `
+            });
+
   deploy-sharing:
     needs: get-build-info
     if: ${{ needs.get-build-info.outputs.branch }}
@@ -667,6 +761,66 @@ jobs:
         generate_release_notes: true
         tag_name: "@stlite/browser@${{ needs.get-changesets-publish-targets.outputs.browser }}"
 
+  publish-react:
+    needs: [get-build-info, get-changesets-publish-targets]
+    if: ${{ needs.get-changesets-publish-targets.outputs.react != '' }}
+
+    permissions:
+      contents: write  # Necessary for creating releases: https://github.com/softprops/action-gh-release#permissions
+      id-token: write  # Necessary for NPM trusted publishing: https://docs.npmjs.com/trusted-publishers#step-2-configure-your-cicd-workflow
+      attestations: read  # Necessary for verifying artifact attestations
+
+    runs-on: ubuntu-latest
+
+    steps:
+    # Checkout for local actions (`uses ./*`).
+    - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+      with:
+        persist-credentials: false
+        sparse-checkout: .github
+        sparse-checkout-cone-mode: false
+
+    - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
+      with:
+        node-version: 22
+        registry-url: 'https://registry.npmjs.org'
+        scope: '@stlite'
+
+    - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+      with:
+        name: stlite-react
+        path: ${{ runner.temp }}/stlite-react
+        run-id: ${{ github.event.workflow_run.id }}
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Verify artifact contents
+      uses: ./.github/actions/verify-only-file
+      with:
+        directory: ${{ runner.temp }}/stlite-react
+        filename: package.tgz
+
+    - name: Verify artifact attestation
+      uses: ./.github/actions/verify-artifact-attestation
+      with:
+        filepath: ${{ runner.temp }}/stlite-react/package.tgz
+        expected-workflow-file: .github/workflows/test-build.yml
+        expected-ref: refs/heads/main
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    # Ensure npm 11.5.1 or later is installed
+    - name: Update npm
+      run: npm install -g npm@latest
+
+    - name: Publish validated package
+      run: npm publish ${{ runner.temp }}/stlite-react/package.tgz --access public
+
+    - name: Create a new release
+      uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2.5.0
+      with:
+        files: ${{ runner.temp }}/stlite-react/package.tgz
+        generate_release_notes: true
+        tag_name: "@stlite/react@${{ needs.get-changesets-publish-targets.outputs.react }}"
+
   publish-desktop:
     needs: [get-build-info, get-changesets-publish-targets]
     if: ${{ needs.get-changesets-publish-targets.outputs.desktop != '' }}

.github/workflows/test-build.yml

@@ -119,6 +119,7 @@ jobs:
       kernel: ${{ steps.filter.outputs.kernel == 'true' || steps.filter.outputs.gha == 'true' || env.RUN_ALL_TESTS == 'true' }}
       # stlite-lib: ${{ steps.filter.outputs.stlite-lib == 'true' || steps.filter.outputs.gha == 'true' || env.RUN_ALL_TESTS == 'true' }}
       stlite-lib: 'true'  # This step does not detect changes in the `streamlit` submodule that is needed to trigger the test-stlite-lib job (https://github.com/dorny/paths-filter/issues/143), so skip checking and make it always return true as a workaround.
+      react: ${{ steps.filter.outputs.react == 'true' || steps.filter.outputs.gha == 'true' || env.RUN_ALL_TESTS == 'true' }}
       browser: ${{ steps.filter.outputs.browser == 'true' || steps.filter.outputs.gha == 'true' || env.RUN_ALL_TESTS == 'true' }}
       sharing: ${{ steps.filter.outputs.sharing == 'true' || steps.filter.outputs.gha == 'true' || env.RUN_ALL_TESTS == 'true' }}
       sharing-editor: ${{ steps.filter.outputs.sharing-editor == 'true' || steps.filter.outputs.gha == 'true' || env.RUN_ALL_TESTS == 'true' }}
@@ -143,6 +144,8 @@ jobs:
           # stlite-lib:  # We run this job anytime. See above.
           #   - 'packages/kernel/py/stlite-lib/**/*'
           #   - 'streamlit/**/*'
+          react:
+            - 'packages/react/**/*'
           browser:
             - 'packages/browser/**/*'
           sharing:
@@ -284,6 +287,32 @@ jobs:
         yarn check:prettier
     - run: yarn test
 
+  test-react:
+    needs: changes
+    if: ${{ needs.changes.outputs.react == 'true' }}
+
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        working-directory: packages/react
+
+    steps:
+    - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+      with:
+        submodules: true
+        persist-credentials: false
+    - uses: ./.github/actions/init-all
+      with:
+        python-version-file: ${{ env.python-version-file }}
+        node-version-file: ${{ env.node-version-file }}
+
+    - name: Lint
+      run: |
+        yarn check:eslint
+        yarn check:prettier
+    - run: yarn test
+
   test-sharing:
     needs: changes
     if: ${{ needs.changes.outputs.sharing == 'true' }}
@@ -486,6 +515,56 @@ jobs:
         name: "streamlit wheel (built as a part of @stlite/browser)"
         input-path: ${{ steps.get-wheel-file-path.outputs.STREAMLIT_WHEEL_FILEPATH }}
 
+  build-react:
+    if: ${{ ! failure() }}  # This job should run even if the depending jobs are skipped, but not when those jobs failed.
+    needs: [set-build-info, test-kernel, test-stlite-lib, test-build-common, test-react]
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      pull-requests: write
+      id-token: write
+      attestations: write
+
+    steps:
+    - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+      with:
+        submodules: true
+        persist-credentials: false
+    - uses: ./.github/actions/init-all
+      with:
+        python-version-file: ${{ env.python-version-file }}
+        node-version-file: ${{ env.node-version-file }}
+
+    - name: Build @stlite/react
+      run: |
+        . .venv/bin/activate
+        make react
+
+    - name: Package
+      working-directory: packages/react
+      run: yarn pack
+
+    - name: Upload the built tar ball as an artifact
+      uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+      with:
+        path: packages/react/package.tgz
+        name: stlite-react
+
+    - name: Generate artifact attestation
+      uses: actions/attest-build-provenance@977bb373ede98d70efdf65b84cb5f73e068dcc2a # v3.0.0
+      with:
+        subject-path: packages/react/package.tgz
+      continue-on-error: true
+
+    - name: "Inform the package stats of @stlite/react"
+      uses: ./.github/actions/set-package-stats
+      continue-on-error: true
+      with:
+        key: react
+        name: "@stlite/react"
+        input-path: packages/react/package.tgz
+
   build-sharing:
     if: ${{ ! failure() }}  # This job should run even if the depending jobs are skipped, but not when those jobs failed: https://qiita.com/abetomo/items/d9ede7dbeeb24f723fc5#%E8%A8%AD%E5%AE%9A%E4%BE%8B4
     needs: [set-build-info, test-kernel, test-stlite-lib, test-sharing-common, test-sharing]

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project Structure & Module Organization
 
-- `packages/` hosts the Yarn workspaces: `browser`, `sharing`, and `desktop` are user apps; `kernel` is the Pyodide core; `sharing-editor` is the editor client for `sharing`, and the rest (`common`, `common-react`, devutils) are support utilities.
+- `packages/` hosts the Yarn workspaces: `browser`, `sharing`, and `desktop` are user apps; `react` is a React library that the apps depend on; `kernel` is the Pyodide core that `react` depends on; `sharing-editor` is the editor client for `sharing`, and the rest (`common`, `sharing-common`, `devutils`) are support utilities.
 - `streamlit/` mirrors upstream Streamlit; `streamlit/frontend/app` is the upstream UI we reference (not build) when customizing `browser`, `sharing`, and `desktop`, while other `streamlit/frontend/*` packages (`lib`, `connection`, etc.) are consumed directly by our workspaces.
 - Supporting assets sit in `assets/`; Makefile orchestrates builds, and browser E2E specs live in `packages/browser/e2e-tests`.
 

Makefile

@@ -43,7 +43,7 @@ STREAMLIT_COMPILED_WHEEL_FILE_NAME := $(shell yarn workspace @stlite/devutils ge
 node_modules := $(BUILD_STATE_DIR)/node_modules/.built
 venv := $(BUILD_STATE_DIR)/venv/.built
 common := $(BUILD_STATE_DIR)/common/.built
-common-react := $(BUILD_STATE_DIR)/common-react/.built
+react := $(BUILD_STATE_DIR)/react/.built
 browser := $(BUILD_STATE_DIR)/browser/.built
 sharing := $(BUILD_STATE_DIR)/sharing/.built
 sharing-common := $(BUILD_STATE_DIR)/sharing-common/.built
@@ -117,13 +117,14 @@ $(common): $(shell \
 	@mkdir -p $(dir $@)
 	@touch $@
 
-.PHONY: common-react
-common-react: $(common-react)
-$(common-react): $(shell \
-	find packages/common-react/src -type f \( -name "*.ts" -o -name "*.tsx" \); \
-	find packages/common-react -maxdepth 1 -type f \( -name "package.json" -o -name "tsconfig*.json" \); \
-) $(node_modules) $(kernel) $(streamlit-frontend-lib)
-	cd packages/common-react && yarn build
+.PHONY: react
+react: $(react)
+$(react): $(shell \
+	find packages/react/src -type f \( -name "*.ts" -o -name "*.tsx" \); \
+	find packages/react/vite-plugin/src -type f -name "*.ts"; \
+	find packages/react -maxdepth 1 -type f \( -name "package.json" -o -name "tsconfig*.json" -o -name "vite.config.ts" \); \
+) $(node_modules) $(kernel) $(common) $(streamlit-frontend-lib)
+	cd packages/react && yarn build
 	@mkdir -p $(dir $@)
 	@touch $@
 
@@ -132,7 +133,7 @@ browser: $(browser)
 $(browser): $(shell \
 	find packages/browser/src -type f \( -name "*.ts" -o -name "*.tsx" \); \
 	find packages/browser -maxdepth 1 -type f \( -name "package.json" -o -name "tsconfig*.json" -o -name "vite.config.ts" \); \
-) $(node_modules) $(kernel) $(common) $(common-react) $(streamlit-frontend-lib)
+) $(node_modules) $(common) $(react)
 	cd packages/browser && yarn build
 	@mkdir -p $(dir $@)
 	@touch $@
@@ -143,7 +144,7 @@ $(sharing): $(shell \
 	find packages/sharing/src -type f \( -name "*.ts" -o -name "*.tsx" \); \
 	find packages/sharing/public -type f; \
 	find packages/sharing -maxdepth 1 -type f \( -name "package.json" -o -name "tsconfig*.json" -o -name "vite.config.ts" \); \
-) $(node_modules) $(kernel) $(sharing-common) $(common-react) $(streamlit-frontend-lib)
+) $(node_modules) $(sharing-common) $(react)
 	cd packages/sharing && yarn build
 	@mkdir -p $(dir $@)
 	@touch $@
@@ -174,7 +175,7 @@ $(desktop): $(shell \
 	find packages/desktop/src -type f \( -name "*.ts" -o -name "*.tsx" \); \
 	find packages/desktop/electron -type f -name "*.ts"; \
 	find packages/desktop -maxdepth 1 -type f \( -name "package.json" -o -name "tsconfig*.json" -o -name "vite.config.ts" \); \
-) $(node_modules) $(kernel) $(common) $(common-react) $(streamlit-frontend-lib)
+) $(node_modules) $(common) $(react)
 	cd packages/desktop && yarn build
 	@mkdir -p $(dir $@)
 	@touch $@