Skip to content

Docs: DO-0 add Dara JS build redesign proposal#623

Draft
krzysztof-causalens wants to merge 9 commits into
masterfrom
codex/dara-js-build-proposal
Draft

Docs: DO-0 add Dara JS build redesign proposal#623
krzysztof-causalens wants to merge 9 commits into
masterfrom
codex/dara-js-build-proposal

Conversation

@krzysztof-causalens
Copy link
Copy Markdown
Collaborator

@krzysztof-causalens krzysztof-causalens commented Apr 16, 2026

Motivation and Context

Dara's current JS build flow relies on a generated dist/ workspace, dara.config.json, machine-dependent Node setup, and a separate UMD / auto-JS path for non-custom-JS apps.

This PR does not change runtime behavior yet. It adds an internal proposal document so the team can review a concrete redesign direction in-repo rather than keeping the design only in chat notes.

The current proposal covers:

  • moving to one Dara-managed cached Node + pnpm toolchain for all apps
  • removing the UMD / auto-JS path so custom-JS and no-custom-JS apps use the same pipeline
  • using a platform-independent dara.lock to avoid cross-platform lock churn
  • making package.json, pnpm-lock.yaml, and dara.lock the checked-in reproducibility surface for every app
  • keeping .dara/, dist/, and node_modules/ as generated or installed state that should not be checked in
  • keeping non-ejected apps simple by having users update the Dara-owned JS surface through dara lock
  • making dara eject the point where the root JS workspace becomes user-owned, with a warning and a narrow merge of Dara-required dependencies
  • exposing Dara's Vite integration through a small @darajs/vite-plugin boundary so ejected configs stay stable and simple
  • validating only the Dara-managed dependency/toolchain surface during local dev, with clear remediation instead of making Dara the owner of unrelated user dependencies
  • migrating away from dara.config.json via compatibility, warn, and enforce phases, with deterministic handling of legacy package-manager settings

Implementation Description

Added a new top-level internal docs area and a draft design proposal at docs-internal/proposals/dara-js-build-redesign.md.

The proposal is intentionally opinionated enough to be actionable, but still leaves a few explicit open questions around the compatibility window for dara.config.json and where ejected source/config files should live by default.

This PR only updates internal documentation. The earlier draft changelog note was removed because this proposal is not a user-facing package change.

Tradeoffs:

  • The draft proposes shipping only a limited set of managed Node targets initially.
  • The draft now favors one always-managed cached toolchain over reusing user-installed Node/pnpm, prioritizing reproducibility and ease of support over flexibility in toolchain sourcing.
  • The default path exposes root package.json and pnpm-lock.yaml as checked-in files for reproducibility, while dara lock remains the normal way for less experienced users to refresh them.
  • Ejection gives experienced users a normal JS workspace and Vite config, with Dara's framework integration kept behind a plugin boundary.
  • The PR title still uses a temporary DO-0 placeholder because no real ticket identifier was provided, but the repo's PR lint requires a ticket-shaped prefix.

Any new dependencies Introduced

None.

How Has This Been Tested?

  • Reviewed the rendered markdown content locally.
  • Ran git diff --check.

No runtime tests were run because this PR only updates an internal proposal document.

PR Checklist:

  • I have implemented all requirements? (see JIRA, project documentation).
  • I am not affecting someone else's work, If I am, they are included as a reviewer.
  • I have added relevant tests (unit, integration or regression).
  • I have added comments to all the bits that are hard to follow.
  • I have added/updated Documentation.
  • I have updated the appropriate changelog with a line for my changes.

Screenshots (if appropriate):

N/A

@krzysztof-causalens krzysztof-causalens self-assigned this Apr 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant