feat(frontend) :: upgrade to typescript

.dockerignore

@@ -13,3 +13,4 @@ examples/
 mssql/
 tests/
 .idea/
+frontend/dist

.github/actions/build-frontend/action.yml

@@ -0,0 +1,15 @@
+name: Build frontend assets
+description: >
+  Installs the npm toolchain and builds the browser bundles that the Rust build
+  embeds. Every job that compiles SQLPage needs this first.
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-node@v6
+      with:
+        node-version: 24
+        cache: npm
+    - run: npm ci
+      shell: bash
+    - run: npm run build
+      shell: bash

.github/workflows/ci.yml

@@ -35,11 +35,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: 24
-          cache: 'npm'
-      - run: npm ci
+      - uses: ./.github/actions/build-frontend
       - run: npm test
       - name: Set up cargo cache
         uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4
@@ -161,6 +157,7 @@ jobs:
     runs-on: windows-latest
     steps:
       - uses: actions/checkout@v6
+      - uses: ./.github/actions/build-frontend
       - name: Set up cargo cache
         uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4
         env:

.github/workflows/release.yml

@@ -30,6 +30,7 @@ jobs:
             features: "odbc-static"
     steps:
       - uses: actions/checkout@v6
+      - uses: ./.github/actions/build-frontend
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
         with:
@@ -87,6 +88,7 @@ jobs:
     container: quay.io/pypa/manylinux_2_28_x86_64
     steps:
       - uses: actions/checkout@v6
+      - uses: ./.github/actions/build-frontend
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
         with:
@@ -155,15 +157,18 @@ jobs:
     if: startsWith(github.ref, 'refs/tags/')
     steps:
       - uses: actions/checkout@v6
+      - uses: ./.github/actions/build-frontend
       - name: Set up cargo cache
         uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4
         env:
           NODE_OPTIONS: --no-deprecation
       - run: sudo apt-get update && sudo apt-get install -y unixodbc-dev
+      # The crate has to carry the frontend built above, and those files are
+      # deliberately untracked: that is all --allow-dirty stands for here.
       - name: Publish to crates.io
         run: |
           set +e
-          cargo publish --token ${{ secrets.CRATES_IO_TOKEN }} 2>&1 | tee cargo-publish.log
+          cargo publish --allow-dirty --token ${{ secrets.CRATES_IO_TOKEN }} 2>&1 | tee cargo-publish.log
           status=${PIPESTATUS[0]}
           set -e
           if [ "$status" -ne 0 ]; then

.gitignore

@@ -14,3 +14,4 @@ sqlpage/sqlpage.db
 tests_uploads/
 /test-results/
 /playwright-report/
+/frontend/dist/

AGENTS.md

@@ -34,7 +34,7 @@ JavaScript where needed.
   retries, and optional `on_connect.sql`/`on_reset.sql` hooks. Database-specific SQL should be isolated or
   covered by the relevant database tests.
 - **Rendering and components** (`src/render.rs`, `src/templates.rs`, `src/dynamic_component.rs`,
-  `src/template_helpers.rs`, `sqlpage/templates/`, `sqlpage/sqlpage.css`, `sqlpage/sqlpage.js`). Built-in components live in `sqlpage/templates/*.handlebars` and cover shells, text,
+  `src/template_helpers.rs`, `sqlpage/templates/`, `frontend/src/`). Built-in components live in `sqlpage/templates/*.handlebars` and cover shells, text,
   tables, lists, cards, charts, forms, navigation, modals, downloads, maps, and more. Query columns map to
   component properties; nested/dynamic components and `sqlpage.run_sql` support composition and lazy loading.
   Custom Handlebars components can be placed in the configured `sqlpage/templates` directory. Raw HTML and
@@ -97,9 +97,10 @@ pattern for the relevant area.
 Mandatory formatting (rust): `cargo fmt --all`
 Mandatory linting: `cargo clippy --all-targets --all-features -- -D warnings`
 
-### When working on css or js
+### When working on css or typescript
 Frontend formatting: `npm run format`
 Mandatory frontend validation: `npm test`
+Rebuild the bundles before any cargo command that has to serve the change: `npm run build`
 
 More about testing: see [github actions](./.github/workflows/ci.yml).
 Contributor setup and validation: see [CONTRIBUTING.md](./CONTRIBUTING.md). Module overview: see [src/lib.rs](./src/lib.rs); architecture diagram: [docs/architecture-detailed.png](./docs/architecture-detailed.png).
@@ -142,4 +143,4 @@ official documentation website sql tables:
 - [Configuration](./configuration.md): see [AppConfig](./src/app_config.rs)
 - Routing: file-based in `src/webserver/routing.rs`. Missing paths use the nearest ancestor `404.sql`; without one, HTML uses `src/default_404.sql` and other formats receive a plain-text 404.
 - Follow patterns from similar modules before introducing new abstractions.
-- frontend: see [css](./sqlpage/sqlpage.css) and [js](./sqlpage/sqlpage.js)
+- frontend: TypeScript and CSS in [frontend/src](./frontend/src), bundled by [frontend/build.mjs](./frontend/build.mjs) into `frontend/dist`, which `build.rs` embeds. Third-party libraries come from npm.

CHANGELOG.md

@@ -12,6 +12,7 @@
  - `column` charts now display vertical bars instead of nothing at all.
  - `stacked` is now ignored on chart types that cannot stack, instead of displaying an empty chart.
  - Screen readers now announce the title of the modal component instead of an unnamed dialog.
+ - The frontend is now TypeScript, bundled with esbuild from npm packages instead of being assembled from CDN downloads at build time. Building SQLPage now requires Node.js: run `npm ci && npm run build` before `cargo build`.
 
 ## v0.45
 

CONTRIBUTING.md

@@ -5,7 +5,7 @@ Thank you for your interest in contributing to SQLPage! This document will guide
 ## Development Setup
 
 1. Install Rust and Cargo (latest stable version): https://www.rust-lang.org/tools/install
-2. If you contribute to the frontend, install Node.js too for frontend tooling: https://nodejs.org/en/download/
+2. Install Node.js: https://nodejs.org/en/download/ . It builds the browser assets that the server embeds.
 3. Clone the repository
 
 ```bash
@@ -19,9 +19,10 @@ The first time you build the project,
 dependencies will be downloaded, so you will need internet access,
 and the build may take a while.
 
-Run the following command from the root of the repository to build the project in development mode:
+Run the following commands from the root of the repository to build the project in development mode:
 
 ```bash
+npm ci && npm run build
 cargo build
 ```
 

Cargo.toml

@@ -8,7 +8,7 @@ license = "MIT"
 homepage = "https://sql-page.com/"
 repository = "https://github.com/sqlpage/SQLPage"
 documentation = "https://docs.rs/sqlpage"
-include = ["/src", "/README.md", "/build.rs", "/sqlpage"]
+include = ["/src", "/README.md", "/build.rs", "/sqlpage", "/frontend/dist"]
 
 [profile.superoptimized]
 inherits = "release"
@@ -130,7 +130,4 @@ actix-http = "3"
 tokio = { version = "1", features = ["rt", "time", "test-util"] }
 
 [build-dependencies]
-awc = { version = "3", features = ["rustls-0_23-webpki-roots"] }
-rustls = "0.23"
-actix-rt = "2.8"
 libflate = "2"

Dockerfile

@@ -1,3 +1,10 @@
+FROM --platform=$BUILDPLATFORM node:24-slim AS frontend
+WORKDIR /usr/src/sqlpage
+COPY package.json package-lock.json tsconfig.json ./
+RUN npm ci --workspaces=false
+COPY frontend/ frontend/
+RUN npm run build
+
 FROM --platform=$BUILDPLATFORM rust:1.95-slim AS builder
 
 WORKDIR /usr/src/sqlpage
@@ -13,7 +20,7 @@ RUN /usr/local/bin/setup-cross-compilation.sh "$TARGETARCH" "$BUILDARCH"
 
 COPY .cargo/ .cargo/
 COPY Cargo.toml Cargo.lock build.rs ./
-COPY sqlpage/ sqlpage/
+COPY --from=frontend /usr/src/sqlpage/frontend/dist frontend/dist
 RUN /usr/local/bin/build-dependencies.sh
 
 COPY . .