DEV Community

Tosiiko
Tosiiko

Posted on

MDL 0.1.9: optional TypeScript behavior scripts without a TypeScript project setup

#webdev #typescript #html #rust

MDL 0.1.9 adds optional external TypeScript behavior scripts.

The important word is optional.

MDL is still:

.mdl  -> structure and content
.css  -> layout and design
.js   -> optional behavior
HTML  -> compiler output
Enter fullscreen mode Exit fullscreen mode

This release does not turn MDL into a JavaScript-app workflow. It does not make
TypeScript a requirement for normal MDL sites. It simply means that if you want
typed behavior modules, MDL can compile local .ts files for the browser during
build and serve.

What changed

Before this release, an MDL project config could include JavaScript module
scripts:

{
  "scripts": [
    "scripts/app.js"
  ]
}
Enter fullscreen mode Exit fullscreen mode

mdl build copied those files unchanged, and generated HTML imported them as
module scripts.

In 0.1.9, the same scripts array can also point at a local TypeScript entry:

{
  "scripts": [
    "scripts/app.ts"
  ]
}
Enter fullscreen mode Exit fullscreen mode

During mdl build, MDL transpiles that entry to JavaScript:

scripts/app.ts -> dist/scripts/app.js
Enter fullscreen mode Exit fullscreen mode

The generated document imports the browser-ready JavaScript URL:

<script type="module">
import * as mdlModule0 from "./scripts/app.js";
</script>
Enter fullscreen mode Exit fullscreen mode

During mdl serve, the page still imports ./scripts/app.js. The dev server
serves that compiled JavaScript from the configured TypeScript source, so the
development URL matches the production URL.

TypeScript trees are supported

The first pass is not limited to a single file. A configured TypeScript entry
can import other local TypeScript modules:

scripts/app.ts
scripts/state/store.ts
scripts/state/model.ts
scripts/dom/forms.ts
scripts/dom/render.ts
scripts/utils/id.ts
Enter fullscreen mode Exit fullscreen mode

MDL follows the local static import/export graph, preserves the folder tree, and
emits matching JavaScript modules:

dist/scripts/app.js
dist/scripts/state/store.js
dist/scripts/state/model.js
dist/scripts/dom/forms.js
dist/scripts/dom/render.js
dist/scripts/utils/id.js
Enter fullscreen mode Exit fullscreen mode

Local TypeScript imports may use .ts, omit the extension, or use the
browser-facing .js extension. MDL rewrites local TypeScript module specifiers
to emitted .js URLs.

For example, this is valid in source:

import { snapshot } from "./state/store.ts";
import { renderTaskList } from "./dom/render.js";
import { byId } from "./dom/query";
import type { TaskFilter } from "./state/model.ts";
Enter fullscreen mode Exit fullscreen mode

The emitted JavaScript uses browser-safe JavaScript module URLs for the local
TypeScript files.

Type-only imports stay type-only. They do not become runtime dependencies.

What MDL does not do

This is transpile-only support for behavior modules.

MDL does not:

  • scaffold package.json
  • create node_modules
  • create tsconfig.json
  • require users to install TypeScript
  • require deployed sites to carry TypeScript
  • bundle npm packages
  • type-check the project yet

Bare package imports and external URLs are left alone. MDL is not trying to be
a bundler in this release.

The TypeScript parser/transpiler lives inside MDL tooling, so a site can use a
configured .ts behavior module without becoming a TypeScript project.

Inline scripts stay JavaScript for now

Inline JavaScript blocks keep working:

script js:
  const form = document.querySelector("#loginForm")
  form?.classList.add("ready")
Enter fullscreen mode Exit fullscreen mode

Inline TypeScript is still unsupported:

script ts:
  // not supported yet
Enter fullscreen mode Exit fullscreen mode

For TypeScript, use an external configured module:

{
  "scripts": [
    "scripts/app.ts"
  ]
}
Enter fullscreen mode Exit fullscreen mode

Event bindings still work the same way

Full-document MDL output imports configured modules and binds exported functions
to MDL behavior attributes:

form@id(taskForm)@submit(createTaskFromForm):
  .input@id(taskTitle)@name(title)@type(text)@input(updateDraftPreview)
  .btn-primary@type(submit)(Add task)

card@id(plannerPanel)@mount(mountPlanner):
  status@id(boardStatus):
    Waiting for the TypeScript module tree.
Enter fullscreen mode Exit fullscreen mode

Your TypeScript module exports the handlers:

export function mountPlanner(element: HTMLElement) {
  element.dataset.ready = "true";
  refresh("Planner mounted from compiled TypeScript.");
}

export function createTaskFromForm(event: SubmitEvent) {
  event.preventDefault();
  // read the form, update state, re-render
}

export function updateDraftPreview(event: Event) {
  // update live preview while the user types
}
Enter fullscreen mode Exit fullscreen mode

MDL handles the wiring. The browser receives JavaScript modules.

New example: examples/typescript

This release adds a more advanced TypeScript example:

examples/typescript
Enter fullscreen mode Exit fullscreen mode

It is a small typed task planner with:

  • a configured scripts/app.ts entry
  • nested state, DOM, and utility modules
  • import type usage
  • imports that use .ts, .js, and extensionless specifiers
  • @mount, @submit, @input, @change, and @click handlers
  • dashboard metrics
  • task filters
  • form parsing
  • toast updates
  • generated dist/scripts/*.js output

Run it:

cd examples/typescript
../../bin/mdl serve
Enter fullscreen mode Exit fullscreen mode

Open:

http://127.0.0.1:3996
Enter fullscreen mode Exit fullscreen mode

Build it:

../../bin/mdl build
Enter fullscreen mode Exit fullscreen mode

The example intentionally has no package.json, no node_modules, and no
tsconfig.json.

Why this shape?

I want MDL to keep a narrow architecture:

MDL source + CSS + optional behavior scripts -> static browser output
Enter fullscreen mode Exit fullscreen mode

Some pages only need HTML and CSS. Some need a little inline JavaScript. Some
need external JavaScript modules. And some behavior is easier to maintain with
TypeScript types.

0.1.9 supports that last case without changing the default model.

The output is still plain browser assets. The project is still inspectable. The
site is still deployable as static files.

Try MDL

Install locally in a project:

mkdir my-mdl-site
cd my-mdl-site
npm install @tosiiko/mdl
npm exec -- mdl init
source bin/activate
mdl serve
Enter fullscreen mode Exit fullscreen mode

Or install globally:

npm install -g @tosiiko/mdl
mdl new my-mdl-site
cd my-mdl-site
mdl serve
Enter fullscreen mode Exit fullscreen mode

Useful commands:

mdl check
mdl format --check
mdl build
mdl serve
Enter fullscreen mode Exit fullscreen mode

Links

MDL is still early, but 0.1.9 makes optional behavior code easier to grow:
JavaScript still works exactly as before, TypeScript can live in local external
modules, and deployed sites only need the compiled JavaScript.

Top comments (0)