Playground improvements

[mandla-enkosi]

This PR improves the Trackkit “playground”/developer experience by expanding workspace coverage (including examples), refining provider/dispatcher configuration handling, adding Playwright E2E coverage, and updating tests/docs to match the new nested provider config shape.

Changes:

Adds examples/* to the pnpm workspace and introduces new example apps.
Updates Trackkit provider configuration to use a nested provider: { name, ... } shape across code, tests, and docs.
Adds Playwright E2E setup for Trackkit and expands diagnostics/dispatcher transport behavior.

[Copilot]

Pull request overview

This PR improves the Trackkit “playground”/developer experience by expanding workspace coverage (including examples), refining provider/dispatcher configuration handling, adding Playwright E2E coverage, and updating tests/docs to match the new nested provider config shape.

Changes:

• Adds examples/* to the pnpm workspace and introduces new example apps.
• Updates Trackkit provider configuration to use a nested provider: { name, ... } shape across code, tests, and docs.
• Adds Playwright E2E setup for Trackkit and expands diagnostics/dispatcher transport behavior.

Reviewed changes

Copilot reviewed 132 out of 135 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
scripts/check.sh	Adjusts task runner helper to respect root scripts vs filtered runs.
pnpm-workspace.yaml	Adds examples/* to workspace packages.
packages/trackkit/vitest.config.ts	Updates Vitest exclusions and coverage exclude patterns.
packages/trackkit/tsup.config.ts	Enables DTS generation in tsup.
packages/trackkit/test/unit/util/env.test.ts	Expands env parsing tests for provider JSON and option collections.
packages/trackkit/test/unit/providers/umami.test.ts	Refactors Umami tests to use sender abstraction + adds error-path cases.
packages/trackkit/test/unit/providers/plausible.test.ts	Refactors Plausible tests to use shared mock sender + updated factory shape.
packages/trackkit/test/unit/providers/noop.test.ts	Updates noop provider tests and adds sender-mirroring coverage.
packages/trackkit/test/unit/providers/loader.test.ts	Updates loader tests for new LoadProviderOptions shape.
packages/trackkit/test/unit/providers/loader-fallback.test.ts	Updates fallback test to new provider config object shape.
packages/trackkit/test/unit/facade/singleton.test.ts	Updates singleton init usage to rely on default provider config.
packages/trackkit/test/unit/facade/policy-gate.test.ts	Refactors policy gate tests to use shared setup helper.
packages/trackkit/test/unit/facade/index.test.ts	Adds diagnostics config assertions and updates expectations.
packages/trackkit/test/unit/errors.test.ts	Updates error tests for nested provider config and typing adjustments.
packages/trackkit/test/unit/dispatcher/transport.test.ts	Adds NoopTransport unit tests.
packages/trackkit/test/unit/dispatcher/resolve-transport.test.ts	Updates resolveTransport tests for new signature with explicit mode.
packages/trackkit/test/unit/dispatcher/batch-processor.test.ts	Updates batch processor tests for new constructor/options shape.
packages/trackkit/test/unit/api/methods.test.ts	Removes explicit noop provider from init calls (default behavior).
packages/trackkit/test/setup/sandbox.ts	Simplifies sandbox setup comments and retains reset behavior.
packages/trackkit/test/setup/msw.ts	Removes console warnings from MSW handlers.
packages/trackkit/test/integration/queue-and-state.test.ts	Adds new integration tests for queue ordering/state.
packages/trackkit/test/integration/providers.test.ts	Updates integration provider configs and adds additional cases.
packages/trackkit/test/integration/navigation.test.ts	Adjusts navigation integration assertion expectations.
packages/trackkit/test/integration/consent/initial.test.ts	Removes explicit noop provider from consent integration tests.
packages/trackkit/test/integration/consent/flow.test.ts	Removes explicit noop provider from consent flow integration tests.
packages/trackkit/test/integration/consent/edge-cases.test.ts	Removes explicit noop provider from consent edge case tests.
packages/trackkit/test/helpers/transport.ts	Updates transport test helper to use shared ID helper; removes dispatcher sender helper.
packages/trackkit/test/helpers/providers.ts	Adds shared mock sender utilities and tightens diagnostics typings.
packages/trackkit/test/fixtures/umami.html	Adds HTML fixture for E2E tests.
packages/trackkit/test/e2e/ga4.spec.ts	Adds Playwright E2E test for GA4 payload structure.
packages/trackkit/test-results/.last-run.json	Adds a test run status artifact file.
packages/trackkit/src/util/types.ts	Adds RequiredExcept / RequiredOnly helper types.
packages/trackkit/src/util/index.ts	Adds ID helpers, exports isPlainObject, introduces deepMerge.
packages/trackkit/src/queues/types.ts	Expands queue type documentation and clarifies queue interface contracts.
packages/trackkit/src/queues/ssr.ts	Uses shared dated ID helper for SSR queue IDs.
packages/trackkit/src/providers/umami/types.ts	Refactors Umami provider options/types to new base provider options + resolved types.
packages/trackkit/src/providers/umami/spec.ts	Updates Umami spec to use resolved options and name discriminator.
packages/trackkit/src/providers/types.ts	Introduces BaseProviderOptions, makes FactoryOptions fields required, refactors provider types.
packages/trackkit/src/providers/stateful-wrapper.ts	Enhances snapshot output and exposes underlying provider instance accessor.
packages/trackkit/src/providers/plausible/types.ts	Refactors Plausible types to base provider options + resolved options type.
packages/trackkit/src/providers/plausible/spec.ts	Updates Plausible spec to use resolved options and name discriminator.
packages/trackkit/src/providers/normalize.ts	Removes old provider normalization module.
packages/trackkit/src/providers/noop/types.ts	Adds typed noop provider options.
packages/trackkit/src/providers/noop/spec.ts	Adds optional mirroring of noop events into a noop sender type for testing.
packages/trackkit/src/providers/metadata.ts	Removes static provider metadata module.
packages/trackkit/src/providers/loader.ts	Refactors provider loading API to accept fully-resolved dispatcher/provider config inputs.
packages/trackkit/src/providers/ga4/types.ts	Refactors GA4 provider option types and resolved options typing.
packages/trackkit/src/providers/ga4/client.ts	Switches GA4 client to use injected sender instead of direct send helper.
packages/trackkit/src/providers/base/transport.ts	Replaces direct sender with dispatcher-backed sender object shape.
packages/trackkit/src/providers/base/adapter.ts	Makes factory options required and routes sends through injected sender.
packages/trackkit/src/performance/tracker.ts	Adds send counters alongside existing event metrics.
packages/trackkit/src/index.ts	Exports ConsentStoredState and DiagnosticsSnapshot types from main entry.
packages/trackkit/src/factory.ts	Renames init options type from InitOptions to AnalyticsOptions.
packages/trackkit/src/facade/singleton.ts	Updates singleton init signature to accept AnalyticsOptions.
packages/trackkit/src/facade/provider-manager.ts	Refactors provider manager to accept resolved facade/dispatcher/provider configs.
packages/trackkit/src/facade/policy-gate.ts	Refactors policy gate to use resolved facade config and adds diagnostics tracking structure.
packages/trackkit/src/facade/normalize.ts	Adds dispatcher defaults resolution and refactors facade default application.
packages/trackkit/src/facade/diagnostics.ts	Expands diagnostics snapshot to include dispatcher + policy + send metrics.
packages/trackkit/src/facade/config.ts	Refactors config merge/resolve flow for nested provider config and dispatcher defaults.
packages/trackkit/src/errors.ts	Adds NOT_INITIALIZED error code.
packages/trackkit/src/dispatcher/transports/resolve.ts	Adds explicit transport mode selection + smart resolution logic and noop transport support.
packages/trackkit/src/dispatcher/transports/proxy.ts	Switches transport ID creation to shared ID helper.
packages/trackkit/src/dispatcher/transports/noop.ts	Adds NoopTransport implementation.
packages/trackkit/src/dispatcher/transports/index.ts	Exports NoopTransport.
packages/trackkit/src/dispatcher/transports/fetch.ts	Switches transport ID creation to shared ID helper.
packages/trackkit/src/dispatcher/transports/beacon.ts	Switches transport ID creation and adds fetch fallback path + error on failure.
packages/trackkit/src/dispatcher/retry.ts	Refactors RetryManager to use resolved retry options and exposes maxAttempts().
packages/trackkit/src/dispatcher/index.ts	Cleans up dispatcher exports.
packages/trackkit/src/dispatcher/batch-processor.ts	Refactors batch processor constructor/options and removes internal retry mechanism.
packages/trackkit/src/dispatcher/adblocker.ts	Types fallback strategy via dispatcher types.
packages/trackkit/src/constants.ts	Adds dispatcher defaults, provider defaults, and refactors default types.
packages/trackkit/src/consent/types.ts	Adds extensive documentation and clarifies resolved consent options/internal types.
packages/trackkit/playwright.config.ts	Adds Playwright config for Trackkit E2E suite.
packages/trackkit/package.json	Adds Playwright scripts and dependency; adjusts verify script invocation.
packages/trackkit/README.md	Updates examples to nested provider config and SSR helper name usage.
package.json	Refactors root scripts to filter packages/examples; adds serve and e2e script wiring.
examples/react-spa-umami/vite.config.ts	Adds Vite config for React SPA example.
examples/react-spa-umami/tsconfig.json	Adds TS config for React SPA example.
examples/react-spa-umami/src/main.tsx	Adds React SPA entrypoint and exposes analytics for debugging.
examples/react-spa-umami/src/analytics.ts	Adds Trackkit instance configuration for Umami example.
examples/react-spa-umami/src/ConsentBanner.tsx	Adds consent banner UI wired to Trackkit consent API.
examples/react-spa-umami/src/App.tsx	Adds SPA navigation demo and Trackkit autoTrack usage.
examples/react-spa-umami/package.json	Adds example package manifest with Trackkit dependency.
examples/react-spa-umami/index.html	Adds example HTML entry.
examples/react-spa-umami/README.md	Adds setup/run instructions for React SPA example.
examples/next-ssr-ga4/tsconfig.json	Adds Next.js example TS config.
examples/next-ssr-ga4/pages/index.tsx	Adds Next.js SSR example page demonstrating SSR queue and client hydration.
examples/next-ssr-ga4/pages/_document.tsx	Adds SSR queue injection into window.__TRACKKIT_SSR_QUEUE__.
examples/next-ssr-ga4/pages/_app.tsx	Adds app wrapper and debug window exposure.
examples/next-ssr-ga4/package.json	Adds Next.js SSR example manifest.
examples/next-ssr-ga4/next.config.ts	Adds Next.js config scaffold.
examples/next-ssr-ga4/next-env.d.ts	Adds Next.js type references.
examples/next-ssr-ga4/lib/analytics.ts	Adds Trackkit instance setup for GA4 in browser-only context.
examples/next-ssr-ga4/README.md	Adds Next.js example README scaffold.
eslint.config.mjs	Ignores .next/ output.
docs/reference/providers.md	Updates provider configuration docs to nested provider object shape.
docs/reference/glossary.md	Updates examples to nested provider config usage.
docs/reference/configuration.md	Updates env/runtime/provider configuration documentation.
docs/reference/api.md	Corrects API docs to match actual signatures/types (AnalyticsOptions, track/pageview/consent).
docs/providers/umami.md	Updates Umami docs for nested provider config and clarified behavior.
docs/providers/plausible.md	Updates Plausible docs for nested provider config.
docs/providers/ga4.md	Updates GA4 docs for nested provider config and measurement-protocol behavior.
docs/overview/what-is-trackkit.md	Updates examples to nested provider config usage.
docs/overview/quickstart.md	Updates quickstart examples and singleton API examples.
docs/overview/faq.md	Updates FAQ references to AnalyticsOptions and SSR helper names.
docs/overview/architecture.md	Updates architecture diagram formatting/indentation.
docs/migration/from-umami.md	Updates migration docs for nested provider config.
docs/migration/from-plausible.md	Updates migration docs for nested provider config.
docs/migration/from-ga4.md	Updates migration docs for nested provider config.
docs/migration/from-env-vars.md	Updates migration docs for nested provider config.
docs/guides/state-management.md	Updates examples for nested provider config.
docs/guides/ssr.md	Updates SSR guide for nested provider config usage.
docs/guides/resilience-and-transports.md	Updates resilience/transport guide wording and examples.
docs/guides/queue-management.md	Updates queue guide examples for nested provider config.
docs/guides/performance-tracking.md	Updates performance guide examples for nested provider config.
docs/guides/consent-management.md	Updates consent guide examples for nested provider config.
docs/guides/connection-and-offline.md	Updates connection/offline guide example for nested provider config.
docs/guides/choosing-provider.md	Updates provider selection guide examples for nested provider config.
docs/examples/next-ssr-ga4.md	Updates Next SSR GA4 docs example for nested provider config.
docdefaults.config.mjs	Removes ResilienceOptions docdefaults entry.
CHANGELOG.md	Adds changelog documenting provider config doc corrections and exported types.
.github/workflows/ci.yml	Adds a Playwright E2E job for Trackkit.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.