Merge pull request #42724 from twbs/issue-42620

Migrate the JavaScript codebase to TypeScript

Author: mdo

.babelrc.mjs

@@ -7,6 +7,14 @@ export default {
         bugfixes: true,
         modules: false
       }
+    ],
+    [
+      '@babel/preset-typescript',
+      {
+        // `declare` fields carry types for constructor-assigned properties
+        // without emitting runtime field definitions
+        allowDeclareFields: true
+      }
     ]
   ]
 }

.bundlewatch.config.json

@@ -34,15 +34,15 @@
     },
     {
       "path": "./dist/js/bootstrap.bundle.js",
-      "maxSize": "88.0 kB"
+      "maxSize": "88.25 kB"
     },
     {
       "path": "./dist/js/bootstrap.bundle.min.js",
       "maxSize": "54.75 kB"
     },
     {
       "path": "./dist/js/bootstrap.js",
-      "maxSize": "59.25 kB"
+      "maxSize": "59.5 kB"
     },
     {
       "path": "./dist/js/bootstrap.min.js",

AGENTS.md

@@ -3,7 +3,7 @@
 Guidance for AI coding agents working in this repository. Tool-agnostic; `CLAUDE.md` points here.
 
 Bootstrap v6.0.0-alpha1 — CSS/JS framework.
-Sass source in `scss/`, JS source in `js/src/`, docs site in `site/` (Astro 5 + MDX).
+Sass source in `scss/`, TypeScript source in `js/src/`, docs site in `site/` (Astro 5 + MDX).
 
 ## Quick commands
 
@@ -28,14 +28,17 @@ Sass source in `scss/`, JS source in `js/src/`, docs site in `site/` (Astro 5 +
 - Modern CSS: `color-mix()`, `light-dark()`, range media queries (`@media (width >= 1024px)`)
 - Doc markers: `// scss-docs-start name` / `// scss-docs-end name` for docs extraction
 
-## JavaScript conventions
+## JavaScript/TypeScript conventions
 
-- ESM-only, no semicolons, 2-space indent
-- Components extend `BaseComponent` (which extends `Config`)
+- Source is TypeScript (`js/src/**/*.ts`, entry `js/index.ts`); ESM-only, no semicolons, 2-space indent
+- Imports use `.js` extensions (standard TS ESM style); the build resolves them to `.ts` via `build/rollup-plugin-ts-resolve.cjs`
+- Strict tsconfig with `verbatimModuleSyntax` + `erasableSyntaxOnly`; Babel (`@babel/preset-typescript`) strips types, `tsc` only type-checks and emits `.d.ts` (`npm run js-typecheck`, `npm run js-compile-types`)
+- Components extend `BaseComponent` (which extends `Config`); per-component config `type XxxConfig` typed off `Default`, refined on the class via `declare _config: XxxConfig`
+- Instance fields use `declare` (no runtime emit); constructor `element` param stays optional to keep `typeof Component` assignable to `typeof BaseComponent`
 - Constants: `NAME`, `DATA_KEY`, `EVENT_KEY`, `VERSION`
-- DOM utilities via `dom/event-handler.js`, `dom/selector-engine.js`, `dom/manipulator.js`
+- DOM utilities via `dom/event-handler.ts`, `dom/selector-engine.ts`, `dom/manipulator.ts`
 - Floating UI for positioning (dropdown, tooltip, popover)
-- Tests: Jasmine + Karma, specs in `js/tests/unit/*.spec.js`
+- Tests: Jasmine + Karma, specs in `js/tests/unit/*.spec.js` (plain JS, bundled against the TS sources); type-level API tests in `js/tests/types/`
 
 ## Docs conventions
 

build/build-plugins.mjs

@@ -6,37 +6,43 @@
  * Licensed under MIT (https://github.com/twbs/bootstrap/blob/main/LICENSE)
  */
 
+import fs from 'node:fs/promises'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { babel } from '@rollup/plugin-babel'
 import { globby } from 'globby'
 import { rollup } from 'rollup'
 import banner from './banner.mjs'
+import tsResolve from './rollup-plugin-ts-resolve.cjs'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 const sourcePath = path.resolve(__dirname, '../js/src/').replace(/\\/g, '/')
-const jsFiles = await globby(`${sourcePath}/**/*.js`)
+const distPath = path.resolve(__dirname, '../js/dist/').replace(/\\/g, '/')
+const tsFiles = await globby(`${sourcePath}/**/*.ts`)
 
 // Array which holds the resolved plugins
 const resolvedPlugins = []
 
-for (const file of jsFiles) {
+for (const file of tsFiles) {
   resolvedPlugins.push({
     src: file,
-    dist: file.replace('src', 'dist'),
-    fileName: path.basename(file)
+    dist: file.replace(sourcePath, distPath).replace(/\.ts$/, '.js'),
+    fileName: path.basename(file).replace(/\.ts$/, '.js')
   })
 }
 
-const build = async plugin => {
+const build = async (plugin, outputOptions = {}) => {
   const bundle = await rollup({
     input: plugin.src,
     plugins: [
+      tsResolve(),
       babel({
         // Only transpile our source code
         exclude: 'node_modules/**',
+        // Transpile the TypeScript sources too
+        extensions: ['.js', '.mjs', '.ts'],
         // Include the helpers in each file, at most one copy of each
         babelHelpers: 'bundled'
       })
@@ -49,12 +55,33 @@ const build = async plugin => {
     format: 'esm',
     sourcemap: true,
     generatedCode: 'es2015',
-    file: plugin.dist
+    file: plugin.dist,
+    ...outputOptions
   })
 
   console.log(`Built ${plugin.fileName}`)
 }
 
+// Build the package entry point next to the plugins. Its re-exports point at
+// `./src/*.ts` sources, so rewrite them to the sibling compiled plugins, and
+// derive the entry's type declarations the same way (the plugins' own
+// declarations are emitted by `js-compile-types`).
+const buildIndex = async () => {
+  const src = path.resolve(__dirname, '../js/index.ts')
+
+  await build(
+    { src, dist: path.resolve(__dirname, '../js/dist/index.js'), fileName: 'index.js' },
+    // The re-exported `./src/*.js` modules live next to the built index —
+    // point at them by filename regardless of how Rollup normalized the ids
+    { paths: id => `./${path.basename(id)}` }
+  )
+
+  const source = await fs.readFile(src, 'utf8')
+  const declarations = source.replace(/'\.\/src\//g, '\'./').replace('Bootstrap index.ts', 'Bootstrap index.d.ts')
+  await fs.writeFile(path.resolve(__dirname, '../js/dist/index.d.ts'), declarations)
+  console.log('Built index.d.ts')
+}
+
 (async () => {
   try {
     const basename = path.basename(__filename)
@@ -63,7 +90,7 @@ const build = async plugin => {
     console.log('Building individual plugins...')
     console.time(timeLabel)
 
-    await Promise.all(Object.values(resolvedPlugins).map(plugin => build(plugin)))
+    await Promise.all([...resolvedPlugins.map(plugin => build(plugin)), buildIndex()])
 
     console.timeEnd(timeLabel)
   } catch (error) {

build/change-version.mjs

@@ -17,7 +17,7 @@ const DRY_RUN = process.argv.includes('--dry') || process.argv.includes('--dry-r
 const FILES = [
   'README.md',
   'config.yml',
-  'js/src/base-component.js',
+  'js/src/base-component.ts',
   'package.js',
   'scss/_banner.scss',
   'site/data/docs-versions.yml'

build/rollup-plugin-ts-resolve.cjs

@@ -0,0 +1,30 @@
+'use strict'
+
+/*!
+ * Rollup plugin that resolves relative `.js` import specifiers to their
+ * TypeScript sources. Our TS files import siblings with the standard
+ * ESM-style `.js` extension (the same way tsc resolves them), so when Rollup
+ * bundles straight from `js/src`, a specifier like `./util/index.js` must be
+ * mapped to the `./util/index.ts` file on disk.
+ * Copyright 2011-2026 The Bootstrap Authors
+ * Licensed under MIT (https://github.com/twbs/bootstrap/blob/main/LICENSE)
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const tsResolve = () => {
+  return {
+    name: 'ts-resolve',
+    resolveId(source, importer) {
+      if (!importer || !source.startsWith('.') || !source.endsWith('.js')) {
+        return null
+      }
+
+      const tsPath = path.resolve(path.dirname(importer), `${source.slice(0, -3)}.ts`)
+      return fs.existsSync(tsPath) ? tsPath : null
+    }
+  }
+}
+
+module.exports = tsResolve

build/rollup.config.mjs

@@ -5,6 +5,7 @@ import { babel } from '@rollup/plugin-babel'
 import { nodeResolve } from '@rollup/plugin-node-resolve'
 import replace from '@rollup/plugin-replace'
 import banner from './banner.mjs'
+import tsResolve from './rollup-plugin-ts-resolve.cjs'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
@@ -13,9 +14,12 @@ const BUNDLE = process.env.BUNDLE === 'true'
 let destinationFile = 'bootstrap'
 const external = ['@floating-ui/dom', 'vanilla-calendar-pro']
 const plugins = [
+  tsResolve(),
   babel({
     // Only transpile our source code
     exclude: 'node_modules/**',
+    // Transpile the TypeScript sources too
+    extensions: ['.js', '.mjs', '.ts'],
     // Include the helpers in the bundle, at most one copy of each
     babelHelpers: 'bundled'
   })
@@ -35,7 +39,7 @@ if (BUNDLE) {
 }
 
 const rollupConfig = {
-  input: path.resolve(__dirname, '../js/index.js'),
+  input: path.resolve(__dirname, '../js/index.ts'),
   output: {
     banner: banner(),
     file: path.resolve(__dirname, `../dist/js/${destinationFile}.js`),

build/tsconfig.dts.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "emitDeclarationOnly": true,
+    "declaration": true,
+    "declarationMap": true,
+    "rootDir": "../js/src",
+    "outDir": "../js/dist"
+  },
+  "include": ["../js/src/**/*.ts"]
+}