Skip to content

Use TypeScript project references for declaration builds #39

Description

@dahlia

PR #38 moves the workspace to the stable TypeScript 7 compiler while preserving declaration generation through tsdown. To keep rolldown-plugin-dts from emitting declarations beside sibling source files, that PR introduces tsconfig.models.json, tsconfig.graphql.json, and tsconfig.drfed.json at the repository root.

Those files are a deliberate workaround rather than the desired ownership model. @drfed/graphql and @drfed/drfed map workspace dependencies to sibling source trees. When the declaration plugin starts from a package-local config, those sources fall outside the root it derives from that config, which can place generated .d.ts and .d.ts.map files under sibling src/ directories. Moving the configs to the repository root contains the output, but also separates declaration settings from the packages they configure.

A direct replacement with tsc --emitDeclarationOnly is not sufficient. With the current source mappings, the GraphQL and application packages still report TS5011 and can emit declarations into sibling source directories. The declaration build needs explicit project boundaries and dependency ordering.

Proposed design

Use TypeScript project references for the packages that publish declarations:

  • Give @drfed/models, @drfed/graphql, and @drfed/drfed package-local declaration configs with composite, declaration, declarationMap, emitDeclarationOnly, rootDir, and outDir set explicitly.
  • Add references that express the build order @drfed/models@drfed/graphql@drfed/drfed.
  • Keep source-oriented paths in the editor/type-checking configs, but make declaration builds consume the outputs of referenced packages.
  • Add a root solution config for tsc -b without moving package-specific compiler settings back to the repository root.
  • Disable declaration generation in tsdown and keep tsdown responsible for JavaScript bundles and source maps.
  • Run the JavaScript and declaration watchers together in scripts/dev.mts.
  • Update package types and exports entries to match the declaration filenames emitted by tsc.
  • Remove tsconfig.models.json, tsconfig.graphql.json, and tsconfig.drfed.json once they are no longer needed.

The web application should remain outside this declaration build graph. packages/web/tsconfig.json is a Vite/SolidStart application config, and @drfed/web does not publish library declarations through tsdown.

Acceptance criteria

  • rolldown-plugin-dts is no longer used by the workspace build.
  • tsc -b emits declarations in package dependency order.
  • Each declaration-producing package owns its declaration config.
  • No generated declaration or declaration map is written under any package's src/ directory.
  • Package types and exports entries resolve to files that are present in dist/.
  • mise run check, mise run build, and mise run test pass.
  • mise run dev rebuilds both JavaScript and declarations after source changes.
  • Packed packages contain the expected declarations, and the installed drfed-server command still starts successfully.

AI usage disclosure

This issue was drafted with assistance from OpenAI Codex (gpt-5.6-sol). Codex inspected the current build configuration, reproduced the declaration-emission failure mode, and helped edit the proposal. The technical conclusions and final wording were reviewed by a DrFed maintainer.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Fields

    Priority

    None yet

    Effort

    None yet

    Projects

    Status
    Todo

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions