feat: compile runtime/shell to JS before publishing

Ship compiled JavaScript + .d.ts declarations instead of raw TypeScript
source. This allows consuming apps to also pre-compile their TypeScript
and use tsc-alias to resolve arbitrary paths (such as @src).

And so that `npm run dev` can also resolve these paths, we add
tsconfig-paths-webpack-plugin to webpack.config.dev.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: arbrandes

.npmignore

@@ -1,6 +1 @@
-__mocks__
 node_modules
-*.test.js
-*.test.jsx
-*.test.ts
-*.test.tsx

Makefile

@@ -11,8 +11,11 @@ doc_command = ./node_modules/.bin/documentation build src -g -c ./docs/documenta
 cat_docs_command = cat ./docs/_API-header.md ./docs/_API-body.md > ./docs/API.md
 
 build:
-	rm -rf ./config ./tools/dist
+	rm -rf ./config ./tools/dist ./dist
 	tsc --project ./tsconfig.json
+	tsc --project ./tsconfig.build.json
+	mkdir -p ./dist/shell
+	cp ./shell/app.scss ./dist/shell/app.scss
 	mkdir -p ./config
 	cp tools/typescript/tsconfig.json config/tsconfig.json
 	tsc --project ./tools/tsconfig.json

docs/decisions/0008-stylesheet-import-in-site-config.md

@@ -21,7 +21,7 @@ As a best practice, a project should have a top-level SCSS file as a peer to the
 The `site.scss` file should import the stylesheet from the shell:
 
 ```diff
-+ @import '@openedx/frontend-base/shell/app.scss';
++ @import '@openedx/frontend-base/dist/shell/app.scss';
 
 // other styles
 ```

docs/how_tos/migrate-frontend-app.md

@@ -128,6 +128,7 @@ With the exception of any custom scripts, replace the `scripts` section of your
 
 ```json
   "scripts": {
+    "build": "tsc --project tsconfig.build.json && tsc-alias -p tsconfig.build.json",
     "dev": "PORT=YOUR_PORT PUBLIC_PATH=/YOUR_APP_NAME openedx dev",
     "i18n_extract": "openedx formatjs extract",
     "lint": "openedx lint .",
@@ -137,6 +138,12 @@ With the exception of any custom scripts, replace the `scripts` section of your
   },
 ```
 
+The `build` script compiles TypeScript to JavaScript and uses `tsc-alias` to rewrite `@src` path aliases to relative paths. You'll need to install `tsc-alias` as a dev dependency:
+
+```sh
+npm install --save-dev tsc-alias
+```
+
 - Replace `YOUR_PORT` with the desired port, of course.
 - Replace  `YOUR_APP_NAME` with the basename used on your site.config, not doing this will result in only the root route working.
 - Note that `fedx-scripts` no longer exists, and has been replaced with `openedx`.
@@ -150,21 +157,24 @@ Other package.json edits
 
 - Change the author to "Open edX"
 
-main
-----
+main and types
+--------------
+
+Point to the compiled output:
 
 ```json
-"main": "src/index.ts",
+"main": "dist/index.js",
+"types": "dist/index.d.ts",
 ```
 
 files
 -----
 
-This is a buildless library, so we package files in `src`:
+Package the compiled output in `dist`:
 
 ```json
 "files": [
-  "/src"
+  "/dist"
 ],
 ```
 
@@ -196,15 +206,10 @@ Finally, make sure the following fields are set properly:
 Clean up .npmignore
 ===================
 
-This is what should be in the repo's `.npmignore`.  No more, no less:
+Since we use the `files` field in `package.json` to whitelist only `/dist`, the `.npmignore` file is largely unnecessary. You can delete it or keep a minimal version:
 
 ```
-__mocks__
 node_modules
-*.test.js
-*.test.jsx
-*.test.ts
-*.test.tsx
 ```
 
 Clean up .gitignore
@@ -259,8 +264,12 @@ Create a `tsconfig.json` file and add the following contents to it:
 {
   "extends": "@openedx/frontend-base/config/tsconfig.json",
   "compilerOptions": {
+    "baseUrl": ".",
     "rootDir": ".",
     "outDir": "dist",
+    "paths": {
+      "@src/*": ["./src/*"]
+    }
   },
   "include": [
     "src/**/*",
@@ -275,6 +284,57 @@ Create a `tsconfig.json` file and add the following contents to it:
 
 This assumes you have a `src` folder and your build goes in `dist`, which is the best practice.
 
+The `@src` path alias
+---------------------
+
+The `paths` configuration above sets up the `@src` alias, which allows you to import from your app's `src` directory using `@src/...` instead of relative paths. For example:
+
+```typescript
+// Instead of:
+import { MyComponent } from '../../../components/MyComponent';
+
+// You can use:
+import { MyComponent } from '@src/components/MyComponent';
+```
+
+For this to work, the app must define its own `@src` path mapping in `tsconfig.json`. **tsc-alias** will then rewrite `@src` imports to relative paths during the build step, so the compiled JavaScript has proper paths.
+
+Add a tsconfig.build.json file
+------------------------------
+
+Create a `tsconfig.build.json` file for compiling your app before publishing:
+
+```json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "noEmit": false,
+    "declaration": true,
+    "declarationMap": false,
+    "sourceMap": false
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "src/**/*.test.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.ts",
+    "src/**/*.spec.tsx",
+    "src/__mocks__/**/*",
+    "src/setupTest.js"
+  ]
+}
+```
+
+This config:
+- Extends your main `tsconfig.json`
+- Outputs compiled JavaScript and type declarations to `dist/`
+- Excludes test files and mocks from the published package
+- Disables source maps for smaller package size
+
 
 Edit jest.config.js
 ===================
@@ -789,7 +849,7 @@ Create a new `app.scss` file at the top of your application.  It's responsible f
 For example:
 
 ```
-@use "@openedx/frontend-base/shell/app.scss";
+@use "@openedx/frontend-base/dist/shell/app.scss";
 @use "sass/style";
 ```
 
@@ -876,17 +936,18 @@ First, rename `src/plugin-slots`, if it exists, to `src/slots`.  Modify imports
 Next, the frontend-base equivalent to `<PluginSlot />` is `<Slot />`, and has a different API.   This includes a change in the slot ID, according to the [new slot naming ADR](../decisions/0009-slot-naming-and-lifecycle.rst) in this repository.  Rename them accordingly. You can refer to the `src/shell/dev` in this repository for examples.
 
 
-Remove build step from CI
-=========================
+Update build step in CI
+=======================
 
-In `.github/workflow/ci.yml`, remove the build step.
+In `.github/workflow/ci.yml`, ensure the build step runs the TypeScript compilation:
 
-```diff
+```yaml
     - name: Test
       run: npm run test
--    - name: Build
--      run: npm run build
+    - name: Build
+      run: npm run build
     - name: i18n_extract
       run: npm run i18n_extract
 ```
-```
+
+The build step compiles TypeScript to JavaScript and rewrites `@src` path aliases using `tsc-alias`.

package-lock.json

@@ -5,13 +5,12 @@
   "publishConfig": {
     "access": "public"
   },
-  "main": "index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
     "/config",
-    "/runtime",
-    "/tools/dist",
-    "/shell",
-    "/types.ts"
+    "/dist",
+    "/tools/dist"
   ],
   "bin": {
     "intl-imports.js": "tools/dist/cli/intl-imports.js",
@@ -118,6 +117,7 @@
     "source-map-loader": "4.0.2",
     "style-loader": "^4.0.0",
     "ts-loader": "^9.5.1",
+    "tsconfig-paths-webpack-plugin": "^4.2.0",
     "typescript": "^5.6.3",
     "typescript-eslint": "^8.11.0",
     "universal-cookie": "^8.0.1",

package.json

@@ -1,8 +1,12 @@
 {
   "extends": "@openedx/frontend-base/config/tsconfig.json",
   "compilerOptions": {
+    "baseUrl": ".",
     "rootDir": ".",
-    "outDir": "dist"
+    "outDir": "dist",
+    "paths": {
+      "@src/*": ["./src/*"]
+    }
   },
   "include": [
     "eslint.config.js",

test-site/tsconfig.json

@@ -5,10 +5,7 @@
     "outDir": "dist",
     "noEmit": false,
     "allowJs": true,
-    "resolveJsonModule": true,
-    "paths": {
-      "@src/*": ["./src/*"]
-    }
+    "resolveJsonModule": true
   },
   "include": [
     "babel/**/*",

tools/tsconfig.json

@@ -24,7 +24,7 @@ const config: Configuration = {
   mode: 'production',
   devtool: 'source-map',
   entry: {
-    app: path.resolve(process.cwd(), 'node_modules/@openedx/frontend-base/shell/site'),
+    app: path.resolve(process.cwd(), 'node_modules/@openedx/frontend-base/dist/shell/site'),
   },
   output: {
     filename: '[name].[chunkhash].js',
@@ -36,7 +36,6 @@ const config: Configuration = {
     alias: {
       ...aliases,
       'site.config': resolvedSiteConfigPath,
-      '@src': path.resolve(process.cwd(), 'src'),
     },
     extensions: ['.js', '.jsx', '.ts', '.tsx'],
   },

tools/webpack/webpack.config.build.ts

@@ -34,7 +34,6 @@ const config: Configuration = {
     alias: {
       ...aliases,
       'site.config': resolvedSiteConfigPath,
-      '@src': path.resolve(process.cwd(), 'src'),
     },
     extensions: ['.js', '.jsx', '.ts', '.tsx'],
   },