Proposal: migrate the repository to a Turborepo-based monorepo

[ribeiroevandro]

Proposal: migrate the repository to a Turborepo-based monorepo

Summary

I would like to propose evolving this repository into a pnpm + Turborepo monorepo structure, with clearer separation between:

• the public aeo.js package
• the website/documentation
• the demo applications
• the shared internal code (core, integrations, widget, CLI)

The goal of this issue is to validate the direction with the maintainers before moving further, so we can avoid spending time on structural work that may not align with the project's long-term direction.

Current problem

Today, the repository centralizes several different responsibilities in the root:

• the public npm package
• library build and type generation
• website/documentation
• framework demos
• operational scripts

This works, but it creates some costs:

• high coupling between library, docs, and demos
• harder dependency maintenance by context
• limited clarity around what is repository infrastructure vs. what belongs to the published package
• more friction when scaling build/test/typecheck by area
• higher risk when evolving internals without affecting the public surface

Proposal

Gradually migrate the repository toward a monorepo with the following direction:

apps/
  docs
  astro
  next
  nuxt
  vite-react
  angular
  webpack

packages/
  aeo.js
  core
  widget
  integrations
  cli
  typescript-config
  eslint-config

Guiding principles:

1. Preserve external compatibility of the aeo.js package
2. Move docs and demos into apps/
3. Extract internal code into packages/
4. Keep the root minimal, focused on orchestration
5. Use package-level tasks, not centralized root task logic

Expected benefits

• clearer isolation between library, docs, and demos
• more predictable builds and validation per package
• better dependency organization
• a stronger foundation for incremental CI and caching
• safer internal refactoring without breaking published exports, subpaths, or binaries

Suggested scope

Phase 1 — Workspace foundation

• adopt pnpm
• add pnpm-workspace.yaml
• add turbo.json
• prepare versioning with Changesets

Phase 2 — App reorganization

• move the website to apps/docs
• move demos to apps/*
• keep transitional compatibility while the public package still lives at the root

Phase 3 — App dependency audit

• review dependencies and peer dependencies for each app
• align versions by framework/toolchain
• decide what can be updated immediately and what should wait until the public package is extracted

Phase 4 — Internal extraction

• extract core, widget, integrations, and cli
• create packages/aeo.js as the public facade
• preserve current exports, subpaths, and binaries

Phase 5 — CI/CD and publishing

• adapt workflows to pnpm/turbo
• validate caching
• prepare release automation with Changesets

Non-goals

This proposal is not intended to:

• change the public API of aeo.js
• remove support for existing public subpaths
• change the aeo.js and aeojs binaries
• introduce breaking changes for package consumers

Questions for maintainers

Before moving forward, it would be helpful to confirm:

1. Is the project open to a monorepo direction?
2. Does separating apps/ and packages/ make sense for this repository?
3. Should the public package continue to be named aeo.js under packages/aeo.js?
4. Should the demos remain in this repository as validation apps?
5. Are there any concerns or constraints around using pnpm, Turborepo, or Changesets?

Minimum acceptance criteria

If this proposal is accepted, I would suggest considering the migration complete only when:

• aeo.js remains publishable without breaking consumers
• all public subpaths still resolve correctly
• the CLI binaries still work
• docs and demos consume local workspaces
• the repository uses a single lockfile
• the consolidated build remains green

Feedback request

If this direction makes sense, I can continue the work in small, reviewable phases, starting with infrastructure/repository organization and leaving the public package extraction as an explicit, controlled step.

[rubenmarcus]

Hey Evandro thats a great proposal, this will be done shortly, as we are developing a chrome extension. this is a great idea