palinxdocs
Get started

Let palinx run it

With palinx you don't write the server. You write pages, and px dev serves them.

Add palinx

Stop the server from the last page, then add the two packages:

bun add @palinx/cli @palinx/core

@palinx/core is the framework your code imports. @palinx/cli provides the px command.

Add a dev script to package.json. bun add already wrote the dependencies, so the scripts block is the only thing you add by hand; the diff is against the last page:

package.json (changes since step 1)
 {
   "name": "my-app",
   "type": "module",
+  "scripts": {
+    "dev": "px dev"
+  },
+  "dependencies": {
+    "@palinx/cli": "^0.5.0",
+    "@palinx/core": "^0.5.0"
+  },
   "devDependencies": {
     "@types/bun": "latest"
   }
 }

Your version range may be newer than ^0.5.0.

Delete index.ts

Delete index.ts. The server you wrote is replaced, and that's the point of this page.

Write a page

Create src/routes/index.route.ts:

src/routes/index.route.ts
// There is no index.ts any more. `px dev` starts the server, and it finds
// this page because the file lives in src/routes/.
import { Route, html } from "@palinx/core";

export default class Home extends Route {
  render() {
    return html`<h1>hello</h1>`;
  }
}

A page is a class that extends Route, exported as the file's default. render() returns the page's markup, written with html: a tagged template literal (a backtick string with a tag) that palinx compiles into DOM, so ${...} values can update in place later.

Run it

bun run dev
$ px dev

  ◀▶ palinx dev server

  Routes: 1 pages, 0 API
[palinx] CSRF is enabled without a secret. Tokens are unsigned, which is vulnerable to subdomain cookie injection. Set security.csrf.secret to a random string (env-sourced) to enable HMAC signing.
  Local:   http://127.0.0.1:2500
  WS:      ws://127.0.0.1:2500

Open http://localhost:2500: a hello heading. Edit the text and save, and the browser updates without a reload. The terminal logs each request, such as [req] GET / 200 3ms.

Leave bun run dev running; the next pages pick up your changes as you save.

How it works

px dev does what your Bun.serve did, and more:

  • It starts the server, on port 2500 unless --port=, PORT or server.port in palinx.config.ts says otherwise.
  • It finds pages by file name: everything in src/routes is a page, and index.route.ts is /.
  • It renders each page on the server for the first paint, then the page's code takes over in the browser.
  • It watches your files and pushes changes to the browser.

The CSRF line is a warning about form protection: with no secret set, tokens aren't signed. This app has no forms, so you can ignore it for now. Configuration covers setting a secret. A 404 for /favicon.ico in the browser console is also expected: the app doesn't have one.

Next: A second page.