refactor: restructure into turbo monorepo (#1143)

Author: overbalance

.claude/CLAUDE.md

@@ -17,22 +17,20 @@ Observability SDK for web applications built on OpenTelemetry. Captures Spans (t
 
 ```bash
 # Build
-npm run sdk:compile              # Build SDK (ESM/CJS/IIFE)
-npm run cli:compile              # Build CLI tool
+npm run build                    # Build all packages (turbo)
 
 # Test
-npm run test                 # Run unit tests
-npm run sdk:test:coverage        # With coverage
-npm run sdk:test:integration     # Integration tests (requires sdk:compile first)
+npm run test                     # Run unit tests (turbo)
+npm run test:integration         # Integration tests (requires build first)
 
 # Lint & Check
-npm run lint             # Auto-fix with Biome
-npm run validate            # All checks (tsc + eslint baseline)
+npm run lint                     # Auto-fix with Biome
+npm run validate                 # All checks (tsc + eslint baseline)
 ```
 
 ## Architecture
 
-### Source Layout (`src/`)
+### Source Layout (`packages/web-sdk/src/`)
 
 ```
 api-*/          Public APIs with no-op defaults (traces, logs, sessions, users, page)
@@ -89,19 +87,19 @@ transport/      HTTP transport with retry logic
 Framework: @web/test-runner + Playwright + Mocha + Chai
 
 ```bash
-npm run sdk:test              # Headless
-npm run sdk:test:manual       # Browser with DevTools
-npm run sdk:test:watch        # Watch mode
+npm run test                  # Headless (from packages/web-sdk/)
+npm run test:manual           # Browser with DevTools
+npm run test:watch            # Watch mode
 ```
 
 ### Integration Tests
 
 Test SDK against bundlers (Webpack 4/5, Vite 7, Next.js):
 
 ```bash
-npm run sdk:compile                       # Build first
-npm run sdk:test:integration              # Run tests
-npm run sdk:test:integration:update-golden  # Update golden files
+npm run build                             # Build first
+npm run test:integration                  # Run tests
+npm run test:integration:update-golden    # Update golden files
 ```
 
 ## Constraints
@@ -132,16 +130,16 @@ npm run sdk:test:integration:update-golden  # Update golden files
 
 ### Adding an Instrumentation
 
-1. Create in `src/instrumentations/<name>/`
+1. Create in `packages/web-sdk/src/instrumentations/<name>/`
 2. Extend `EmbraceInstrumentationBase`
-3. Export from `src/instrumentations/index.ts`
+3. Export from `packages/web-sdk/src/instrumentations/index.ts`
 4. Register in `setupDefaultInstrumentations.ts` if auto-enabled
 
 ### Adding a Processor
 
-1. Create in `src/processors/<Name>Processor/`
+1. Create in `packages/web-sdk/src/processors/<Name>Processor/`
 2. Implement `SpanProcessor` or `LogRecordProcessor`
-3. Export from `src/processors/index.ts`
+3. Export from `packages/web-sdk/src/processors/index.ts`
 4. Wire into processor chain in `initSDK.ts`
 
 ## Git Workflow
@@ -194,5 +192,5 @@ npm run sdk:test:integration:update-golden  # Update golden files
 
 ### Tests Flaky
 
-- Ensure `npm run sdk:compile` before integration tests
-- Use `sdk:test:manual` for debugging
+- Ensure `npm run build` before integration tests
+- Use `npm run test:manual` for debugging (from `packages/web-sdk/`)

.github/workflows/ci-nodejs.yml

@@ -112,13 +112,13 @@ jobs:
       # playwright to install everything for us.
       - name: Install Playwright browsers with dependencies
         if: ${{ env.TEST_PREVIOUSLY_PASSED != 'true' && steps.playwright-cache.outputs.cache-hit != 'true' }}
-        run: npm run playwright -- install --with-deps
+        run: npx playwright install --with-deps
 
       # If the Playwright browser binaries were restored, we tell
       # playwright to install just system deps.
       - name: Install Playwright's dependencies
         if: ${{ env.TEST_PREVIOUSLY_PASSED != 'true' && steps.playwright-cache.outputs.cache-hit == 'true' }}
-        run: npm run playwright -- install-deps
+        run: npx playwright install-deps
 
       - name: Test with coverage
         if: ${{ env.TEST_PREVIOUSLY_PASSED != 'true' }}
@@ -130,7 +130,7 @@ jobs:
             argsCoverage='--config=web-test-runner.coverage.config.js'
             echo 'TEST_COLLECTED_COVERAGE=true' >> $GITHUB_ENV
           fi
-          npm run sdk:test -- $argsCoverage
+          npx turbo run test --filter=@embrace-io/web-sdk -- $argsCoverage
         env:
           GITHUB_EVENT_ACTION: ${{ github.event.action }}
 
@@ -222,18 +222,18 @@ jobs:
       # playwright to install everything for us.
       - name: Install Playwright browsers with dependencies
         if: ${{ env.TEST_PREVIOUSLY_PASSED != 'true' && steps.playwright-cache.outputs.cache-hit != 'true' }}
-        run: npm run playwright -- install --with-deps
+        run: npx playwright install --with-deps
 
       # If the Playwright browser binaries were restored, we tell
       # playwright to install just system deps.
       - name: Install Playwright's dependencies
         if: ${{ env.TEST_PREVIOUSLY_PASSED != 'true' && steps.playwright-cache.outputs.cache-hit == 'true' }}
-        run: npm run playwright -- install-deps
+        run: npx playwright install-deps
 
       - name: Test SDK multiple browsers
         if: ${{ env.TEST_PREVIOUSLY_PASSED != 'true' }}
         run: |
-          npm run sdk:test:multiBrowsers
+          npm run test:multiBrowsers
 
       - name: Cache successful test results
         if: ${{ success() }}
@@ -325,24 +325,18 @@ jobs:
       # playwright to install everything for us.
       - name: Install Playwright browsers with dependencies
         if: ${{ env.TEST_PREVIOUSLY_PASSED != 'true' && steps.playwright-cache.outputs.cache-hit != 'true' }}
-        run: npm run playwright -- install --with-deps
+        run: npx playwright install --with-deps
 
       # If the Playwright browser binaries were restored, we tell
       # playwright to install just system deps.
       - name: Install Playwright's dependencies
         if: ${{ env.TEST_PREVIOUSLY_PASSED != 'true' && steps.playwright-cache.outputs.cache-hit == 'true' }}
-        run: npm run playwright -- install-deps
-
-      # We need the SDK to be built, so we can use it during performance tests
-      - name: Build SDK
-        if: ${{ env.TEST_PREVIOUSLY_PASSED != 'true' }}
-        run: |
-          npm run sdk:compile
+        run: npx playwright install-deps
 
       - name: Test performance
         if: ${{ env.TEST_PREVIOUSLY_PASSED != 'true' }}
         run: |
-          npm run sdk:test:performance
+          npm run test:performance
 
       - name: Cache successful test results
         if: ${{ success() }}
@@ -458,7 +452,7 @@ jobs:
       - name: Test CLI
         if: ${{ env.TEST_PREVIOUSLY_PASSED != 'true' }}
         run: |
-          npm run test --prefix cli
+          npx turbo run test --filter=@embrace-io/web-cli
 
       - name: Cache successful test results
         if: ${{ success() }}
@@ -542,26 +536,20 @@ jobs:
       # playwright to install everything for us.
       - name: Install Playwright browsers with dependencies
         if: ${{ env.TEST_PREVIOUSLY_PASSED != 'true' && steps.playwright-cache.outputs.cache-hit != 'true' }}
-        run: npm run playwright -- install --with-deps
+        run: npx playwright install --with-deps
 
       # If the Playwright browser binaries were restored, we tell
       # playwright to install just system deps.
       - name: Install Playwright's dependencies
         if: ${{ env.TEST_PREVIOUSLY_PASSED != 'true' && steps.playwright-cache.outputs.cache-hit == 'true' }}
-        run: npm run playwright -- install-deps
-
-      # We need the SDK and CLI to be built, so we can use them in the sample apps
-      - name: Build SDK and CLI
-        if: ${{ env.TEST_PREVIOUSLY_PASSED != 'true' }}
-        run: |
-          npm run compile
+        run: npx playwright install-deps
 
       - name: Test Integration
         if: ${{ env.TEST_PREVIOUSLY_PASSED != 'true' }}
         # Build needs to run first so e2e tests can use the built apps and not build again
         # Run the e2e tests in a virtual display, since Playwright needs a display to run
         run: |
-          npm run sdk:test:integration
+          npm run test:integration
 
       - name: Cache successful test results
         if: ${{ success() }}
@@ -695,7 +683,7 @@ jobs:
       - name: Lint
         if: ${{ env.LINT_PREVIOUSLY_PASSED != 'true' }}
         run: |
-          npm run sdk:lint
+          npm run lint
 
       - name: Cache successful lint results
         if: ${{ success() }}
@@ -748,7 +736,7 @@ jobs:
       - name: Type check
         if: ${{ env.TYPE_CHECK_PREVIOUSLY_PASSED != 'true' }}
         run: |
-          npm run sdk:check
+          npm run check
 
       - name: Cache successful type check results
         if: ${{ success() }}
@@ -800,30 +788,15 @@ jobs:
         run: |
           npm ci
 
-      - name: Build SDK
-        if: ${{ env.VALIDATE_PREVIOUSLY_PASSED != 'true' }}
-        run: |
-          npm run sdk:compile
-
-      - name: Validate SDK
-        if: ${{ env.VALIDATE_PREVIOUSLY_PASSED != 'true' }}
-        run: |
-          npm run sdk:validate
-
-      - name: Build CLI
-        if: ${{ env.VALIDATE_PREVIOUSLY_PASSED != 'true' }}
-        run: |
-          npm run cli:compile
-
-      - name: Validate CLI
+      - name: Build All Packages
         if: ${{ env.VALIDATE_PREVIOUSLY_PASSED != 'true' }}
         run: |
-          npm run cli:validate
+          npm run build
 
-      - name: Build Demo
+      - name: Validate Packages
         if: ${{ env.VALIDATE_PREVIOUSLY_PASSED != 'true' }}
         run: |
-          npm run build --prefix demo/frontend
+          npm run validate
 
       - name: Cache successful validate results
         if: ${{ success() }}
@@ -868,15 +841,16 @@ jobs:
 
       - name: Build SDK and CLI
         run: |
-          npm run compile
+          npm run build
 
       - name: Publish SDK
         run: |
+          cd packages/web-sdk
           npm publish --provenance --access public
 
       - name: Publish CLI
         run: |
-          cd cli
+          cd packages/web-cli
           npm publish --provenance --access public
 
   # Publishes preview packages to pkg.pr.new after CI passes on main.
@@ -910,10 +884,10 @@ jobs:
         run: npm ci
 
       - name: Build SDK and CLI
-        run: npm run compile
+        run: npm run build
 
       - name: Publish preview packages
-        run: npx --yes pkg-pr-new publish --compact '.' './cli'
+        run: npx --yes pkg-pr-new publish --compact './packages/web-sdk' './packages/web-cli'
 
   # not used yet, there are no "production" releases
   report-release-slack:

.github/workflows/pkg-pr-new.yml

@@ -29,7 +29,7 @@ jobs:
         run: npm ci
 
       - name: Build SDK and CLI
-        run: npm run compile
+        run: npm run build
 
       - name: Publish preview packages
-        run: npx --yes pkg-pr-new publish --compact '.' './cli'
+        run: npx --yes pkg-pr-new publish --compact './packages/web-sdk' './packages/web-cli'

.github/workflows/publish-demo.yaml

@@ -6,7 +6,7 @@ on:
     paths:
       - demo/**
       - package*.json
-      - src/**
+      - packages/web-sdk/src/**
       - .nvmrc
   workflow_dispatch:
 
@@ -38,9 +38,7 @@ jobs:
       - run: npm ci
 
       - name: Build demo
-        run: npm run build --prefix demo/frontend
-        env:
-          VITE_BASE_URL: /embrace-web-sdk/
+        run: npx turbo run build --filter=embrace-web-sdk-react-demo
 
       - name: Verify build output
         run: |

.github/workflows/release.yaml

@@ -63,7 +63,7 @@ jobs:
           # commit the changes
           git config --global user.name 'embrace-ci'
           git config --global user.email 'embrace-ci@users.noreply.github.com'
-          git add package.json package-lock.json cli/package.json src/resources/constants/index.ts cli/src/constants.ts tests/integration/tests/__golden__
+          git add packages/web-sdk/package.json package-lock.json packages/web-cli/package.json packages/web-sdk/src/resources/constants/index.ts packages/web-cli/src/constants.ts tests/integration/tests/__golden__
           git commit -m "release: update version to $NEXT_VERSION"
           git push origin "release-$NEXT_VERSION"
           # create a PR with the next version

.gitignore

@@ -13,3 +13,4 @@ dist
 .tmp*/
 test-results
 build-test-results
+.turbo/

DEVELOPING.md

@@ -24,7 +24,7 @@ This command will:
 
 ## Repo Layout
 
-The code within `src/` is divided as follows:
+The code within `packages/web-sdk/src/` is divided as follows:
 
 - `api-*/`
   - High-level APIs that expose the SDK's functionality. By default these
@@ -63,36 +63,39 @@ together).
 Run tests with:
 
 ```sh
-npm run sdk:test
+npm run test
 ```
 
 For debugging, you can run tests in a browser to set breakpoints, open the dev
 console, etc. with:
 
 ```sh
-npm run sdk:test:manual
+npm run test:manual
 ```
 
 Manual mode as well as other debugging options can also be reached from watch
 mode:
 
 ```sh
-npm run sdk:test:watch
+npm run test:watch
 ```
 
+> Note: These commands should be run from `packages/web-sdk/`. From the repo
+> root, `npm run test` runs tests across all packages via Turbo.
+
 ## Integration Testing
 
 Run the integration tests and build all prerequisites with:
 
 ```bash
-npm run sdk:compile
-npm run sdk:test:integration
+npm run build
+npm run test:integration
 ```
 
 To update golden files replace the last command with:
 
 ```bash
-npm run sdk:test:integration:update-golden
+npm run test:integration:update-golden
 ```
 
 ## Dependency Versioning