setup repository structure, path, env configs and convention

[debuggingfuture]

This issue is to keep track of various considerations, will be closed once concluded with documentations

(WIP)

Background

• current development (storybook, vitest) make use of vite config, which default to use import.meta.env and expect env variables prefixed e.g. VITE_

Our take

ESM

• we do not intend to publish most components as library, we do not bundle and transpile to cjs
• we prefer to structure components as just in time package as we have no intention to export, so as to benefit perf by avoiding intermediate build step
• We should support the end-application to decide given their own bundler, which for now we don't support application that do not support import / esm

path alias

• shadn use components.json alias

  • reference: https://turbo.build/repo/docs/guides/tools/typescript#use-nodejs-subpath-imports-instead-of-typescript-compiler-paths

• tsconfig paths alias is not sufficient and we use nodejs subpath imports

  • i.e. imports at package.json for the # alias

• to support IDE, we need array with explicit extension. Note order matters so IDE can process accordingly

	"imports": {
		"#*": ["./src/*", "./src/*.tsx"]
	},

IDE config

This is expected for auto import to work.

• includePackageJsonAutoImports is to trade off performance for full search on paths for all internal packages, so as to support wildcard import

• importModuleSpecifierEnding is to avoid automatically adding .js extension, , although in practice we find it a bit fuzzy

	"typescript.preferences.includePackageJsonAutoImports": "on",
	"typescript.preferences.importModuleSpecifierEnding": "minimal",

Env config

• As we try to be agnostic and align common convention

• we support .env

• avoid the vite convention of import.meta.env and stick with process.env

• to achieve this, we have

  1. explicit define process.env https://vite.dev/config/
  2. use loadEnv at vite to load env onto storybook and tests

• we prefer to name space env variables, and for now we use canonical util config at packages/domain/src/config.ts

• avoid loading environment directly at components / libs (e.g. process.env) and always prefer injecting config

_{Huly®: DAPPK-58}

• we could consider use of defu https://github.com/unjs/defu to merge config

Vite config

• support project root config
  https://vite.dev/config/#configuring-vite

• vite config need to be customize for dom based testing at storybook / ui-react packages

  • for now we install related dependencies at root