[Tracking Issue] Share code between sides

[Tobbe]

I'm going to spend some time working on sharing code between the web and the api side.
Opening this issue to track the progress

This is what needs to work:

• yarn cedar g package <name>
  • Updates the root package.json file (feat(cca): Use modern workspace config #751 was a prerequisite for this)
  • Writes generic tsconfig, package.json, etc files for a package
  • Runs yarn install to let yarn know about the new package
  • Runs yarn build to make it possible to start using the package right away
    • Update this to leverage yarn cedar build <packageName> when possible
• When running yarn cedar dev both the web and api sides can import and use the code in the package
• When running yarn cedar dev HMR works for both the web and api sides
• When building and then running yarn cedar serve, both the web and api sides can import and use the code
• When deploying, the shared code is properly built on the deploy provider's side
  • Docker
  • Serverless (i.e. Netlify)
  • Baremetal
• Unit testing works
  • api code that uses shared code
  • web code that uses shared code
  • tests specifically for the shared code only
• yarn cedar upgrade also updates packages with the new version of Cedar packages
• yarn cedar dev, yarn cedar test and other cli commands works inside package directories
• It's possible to tweak the templates used for new packages (chore(cli): Refactor template handling in generators #761 and feat(cli): Custom script templates #813 were prerequisites for this)
• git should ignore tsbuildinfo files
  • Update templates' .gitignore files
  • Make the package generator update .gitignore if needed
• Document the new shared code feature
  • General "shared code" docs
  • Cedar CLI docs
• Update yarn cedar build
  • To build all packages (in addition to web and api) when run without arguments
  • To allow passing a package name to build only that package

[Tobbe]

Here's a SO question about having Vite's HMR working with workspaces https://stackoverflow.com/questions/79011328/vite-hmr-not-working-with-monorepo-package

Two vitejs resources worth reading for setting this up.
vitejs/vite#10447
vitejs/vite#7155

tsconfig module node20
microsoft/TypeScript#60761

node20 adds support for require(ESM).

from: https://www.typescriptlang.org/tsconfig/#node16node18node20nodenext

[Tobbe]

Should also produce a package.json file with the correct "type" field depending on what the web and api sides already useAlways generating ESM packages 🎉

And I need to figure out how to make yarn cedar work inside packages/package-name/ folders

[Tobbe]

I had to decide if I should use CommonJS or ESModules for shared packages ("type": "commonjs" or "type": "module" in the package's package.json). Obviously ESM would be the better and more future proof option. It's also what Vite prefers. Traditionally Cedar's API side couldn't use ESM packages though.

Trying to use a shared package on the API side confirms this ESM incompatibility by showing this error

The current file is a CommonJS module whose imports will produce require calls; however, the referenced file is an ECMAScript module and cannot be imported with require. Consider writing a dynamic import("@cedar-share-code/foobar") call instead. To convert this file to an ECMAScript module, change its file extension to .mts, or add the field "type": "module" to /Users/tobbe/tmp/cedar-share-code/api/package.json. (ts 1479)

This is slightly confusing though, because Node 24, which we're using, is supposed to allow require of ESM code.

Turns out there was one final thing needed to make it all work – had to update the tsconfig on the api side. module should now be node20. That tells TypeScript that we're targeting a new enough version of node for esm require.

So thanks to the recent Node 24 upgrade, which supports require() of ES modules, and an easy update to Cedar apps' tsconfig, ESM packages can finally be used on the API side too 🎉