create-acrylblends 0.0.0-stage → 0.1.1

package/docs/framework/getting-started/bun.md

@@ -0,0 +1,221 @@
+# Bun
+
+> **Experimental.** Bun is not a verified runtime yet: the Acryl application code is the same, but the `bun` template and this guide are not covered by the release checks. Node.js is the verified runtime.
+
+
+[Bun](https://bun.com) is another JavaScript runtime. It's not Node.js. Bun includes a transcompiler, so we can write the code in TypeScript or plain JavaScript.
+Acryl also works on Bun.
+
+## 1. Install Bun
+
+To install `bun` command, follow the instruction in [the official web site](https://bun.com).
+
+## 2. Setup
+
+### 2.1. Setup a new project
+
+A starter for Bun is available. Start your project with "bun create" command.
+Select `bun` template for this example.
+
+```sh
+bun create acrylblends@latest my-app
+```
+
+Move into my-app and install the dependencies.
+
+```sh
+cd my-app
+bun install
+```
+
+### 2.2. Setup an existing project
+
+On an existing Bun project, we only need to install `acrylblends` dependencies on the project root directory via
+
+```sh
+bun add acrylblends
+```
+
+Then add the `dev` command to your existing `package.json`.
+
+```json
+{
+  "scripts": {
+    "dev": "bun run --hot src/index.ts"
+  }
+}
+```
+
+See the Bun starter template for a minimal example setup. This is the output of running `bun create acrylblends@latest`.
+
+## 3. Hello World
+
+"Hello World" script is below. Almost the same as writing on other platforms.
+
+```ts
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+app.get('/', (c) => c.text('Hello Bun!'))
+
+export default app
+```
+
+If you are setting up Acryl on an existing project, the `bun run dev` command expects the "Hello World" script to be placed in `src/index.ts`
+
+## 4. Run
+
+Run the command.
+
+```sh
+bun run dev
+```
+
+Then, access `http://localhost:3000` in your browser.
+
+## Change port number
+
+You can specify the port number with exporting the `port`.
+
+<!-- prettier-ignore -->
+```ts
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+app.get('/', (c) => c.text('Hello Bun!'))
+
+export default {
+  port: 3000,
+  fetch: app.fetch,
+}
+```
+
+## Serve static files
+
+To serve static files, use `serveStatic` from `acrylblends/bun`.
+
+> **Not yet available.** The Bun adapter, `acrylblends/bun`, is not part of acrylblends yet. The code below shows the planned usage.
+
+```ts
+import { serveStatic } from 'acrylblends/bun'
+
+const app = new Acryl()
+
+app.use('/static/*', serveStatic({ root: './' }))
+app.use('/favicon.ico', serveStatic({ path: './favicon.ico' }))
+app.get('/', (c) => c.text('You can access: /static/hello.txt'))
+app.get('*', serveStatic({ path: './static/fallback.txt' }))
+```
+
+For the above code, it will work well with the following directory structure.
+
+```
+./
+├── favicon.ico
+├── src
+└── static
+    ├── demo
+    │   └── index.html
+    ├── fallback.txt
+    ├── hello.txt
+    └── images
+        └── dinotocat.png
+```
+
+### `rewriteRequestPath`
+
+If you want to map `http://localhost:3000/static/*` to `./statics`, you can use the `rewriteRequestPath` option:
+
+```ts
+app.get(
+  '/static/*',
+  serveStatic({
+    root: './',
+    rewriteRequestPath: (path) =>
+      path.replace(/^\/static/, '/statics'),
+  })
+)
+```
+
+### `mimes`
+
+You can add MIME types with `mimes`:
+
+```ts
+app.get(
+  '/static/*',
+  serveStatic({
+    mimes: {
+      m3u8: 'application/vnd.apple.mpegurl',
+      ts: 'video/mp2t',
+    },
+  })
+)
+```
+
+### `onFound`
+
+You can specify handling when the requested file is found with `onFound`:
+
+```ts
+app.get(
+  '/static/*',
+  serveStatic({
+    // ...
+    onFound: (_path, c) => {
+      c.header('Cache-Control', `public, immutable, max-age=31536000`)
+    },
+  })
+)
+```
+
+### `onNotFound`
+
+You can specify handling when the requested file is not found with `onNotFound`:
+
+```ts
+app.get(
+  '/static/*',
+  serveStatic({
+    onNotFound: (path, c) => {
+      console.log(`${path} is not found, you access ${c.req.path}`)
+    },
+  })
+)
+```
+
+### `precompressed`
+
+The `precompressed` option checks if files with extensions like `.br` or `.gz` are available and serves them based on the `Accept-Encoding` header. It prioritizes Brotli, then Zstd, and Gzip. If none are available, it serves the original file.
+
+```ts
+app.get(
+  '/static/*',
+  serveStatic({
+    precompressed: true,
+  })
+)
+```
+
+## Testing
+
+You can use `bun:test` for testing on Bun.
+
+```ts
+import { describe, expect, it } from 'bun:test'
+import app from '.'
+
+describe('My first test', () => {
+  it('Should return 200 Response', async () => {
+    const req = new Request('http://localhost/')
+    const res = await app.fetch(req)
+    expect(res.status).toBe(200)
+  })
+})
+```
+
+Then, run the command.
+
+```sh
+bun test index.test.ts
+```

package/docs/framework/getting-started/nodejs.md

@@ -0,0 +1,344 @@
+# Node.js
+
+[Node.js](https://nodejs.org/) is an open-source, cross-platform JavaScript runtime environment.
+
+On Node.js, Acryl runs through the Node.js adapter, `acrylblends/node-server`.
+
+> **Note.** Verified on Node.js 22.19 and newer, which runs TypeScript files directly.
+
+## 1. Setup
+
+A starter for Node.js is available.
+Start your project with "create-acrylblends" command.
+Select `nodejs` template for this example.
+
+**npm**
+
+```sh
+npm create acrylblends@latest my-app
+```
+
+**yarn**
+
+```sh
+yarn create acrylblends my-app
+```
+
+**pnpm**
+
+```sh
+pnpm create acrylblends my-app
+```
+
+**bun**
+
+```sh
+bun create acrylblends@latest my-app
+```
+
+Move to `my-app` and install the dependencies.
+
+**npm**
+
+```sh
+cd my-app
+npm i
+```
+
+**yarn**
+
+```sh
+cd my-app
+yarn
+```
+
+**pnpm**
+
+```sh
+cd my-app
+pnpm i
+```
+
+**bun**
+
+```sh
+cd my-app
+bun i
+```
+
+## 2. Hello World
+
+Edit `src/index.ts`:
+
+```ts
+import { serve } from 'acrylblends/node-server'
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+app.get('/', (c) => c.text('Hello Node.js!'))
+
+serve(app)
+```
+
+If you want to gracefully shut down the server, write it like this:
+
+```ts
+const server = serve(app)
+
+// graceful shutdown
+process.on('SIGINT', () => {
+  server.close()
+  process.exit(0)
+})
+process.on('SIGTERM', () => {
+  server.close((err) => {
+    if (err) {
+      console.error(err)
+      process.exit(1)
+    }
+    process.exit(0)
+  })
+})
+```
+
+> **Note.** On Node.js, `serve()` wraps the `node:http` module and returns the underlying server instance, so closing it is up to you. Bun serves Fetch handlers natively and manages the server itself, which is why its guide doesn't include this step.
+
+## 3. Run
+
+Run the development server locally. Then, access `http://localhost:3000` in your Web browser.
+
+**npm**
+
+```sh
+npm run dev
+```
+
+**yarn**
+
+```sh
+yarn dev
+```
+
+**pnpm**
+
+```sh
+pnpm dev
+```
+
+## Change port number
+
+You can specify the port number with the `port` option.
+
+```ts
+serve({
+  fetch: app.fetch,
+  port: 8787,
+})
+```
+
+## WebSocket
+
+WebSocket support is built into `acrylblends/node-server`. Install `ws` and, if you use TypeScript, `@types/ws`. Then create a `WebSocketServer` with `{ noServer: true }` and pass it to `serve()` with the `websocket` option.
+
+```ts
+import { serve, upgradeWebSocket } from 'acrylblends/node-server'
+import { Acryl } from 'acrylblends'
+import { WebSocketServer } from 'ws'
+
+const app = new Acryl()
+
+app.get(
+  '/ws',
+  upgradeWebSocket(() => ({
+    onMessage(event, ws) {
+      ws.send(String(event.data))
+    },
+  }))
+)
+
+const wss = new WebSocketServer({ noServer: true })
+
+serve({
+  fetch: app.fetch,
+  websocket: { server: wss },
+})
+```
+
+## Access the raw Node.js APIs
+
+You can access the Node.js APIs from `c.env.incoming` and `c.env.outgoing`.
+
+```ts
+import { Acryl } from 'acrylblends'
+import { serve, type HttpBindings } from 'acrylblends/node-server'
+// or `Http2Bindings` if you use HTTP2
+
+type Bindings = HttpBindings & {
+  /* ... */
+}
+
+const app = new Acryl<{ Bindings: Bindings }>()
+
+app.get('/', (c) => {
+  return c.json({
+    remoteAddress: c.env.incoming.socket.remoteAddress,
+  })
+})
+
+serve(app)
+```
+
+## Serve static files
+
+You can use `serveStatic` to serve static files from the local file system. For example, suppose the directory structure is as follows:
+
+```sh
+./
+├── favicon.ico
+├── index.ts
+└── static
+    ├── hello.txt
+    └── image.png
+```
+
+If a request to the path `/static/*` comes in and you want to return a file under `./static`, you can write the following:
+
+```ts
+import { serveStatic } from 'acrylblends/node-server'
+
+app.use('/static/*', serveStatic({ root: './' }))
+```
+
+**Warning.**
+
+The `root` option resolves paths relative to the current working directory (`process.cwd()`). This means the behavior depends on **where you run your Node.js process from**, not where your source file is located. If you start your server from a different directory, file resolution may fail.
+
+For reliable path resolution that always points to the same directory as your source file, use `import.meta.url`:
+
+```ts
+import { fileURLToPath } from 'node:url'
+import { serveStatic } from 'acrylblends/node-server'
+
+app.use(
+  '/static/*',
+  serveStatic({ root: fileURLToPath(new URL('./', import.meta.url)) })
+)
+```
+
+Use the `path` option to serve `favicon.ico` in the directory root:
+
+```ts
+app.use('/favicon.ico', serveStatic({ path: './favicon.ico' }))
+```
+
+If a request to the path `/hello.txt` or `/image.png` comes in and you want to return a file named `./static/hello.txt` or `./static/image.png`, you can use the following:
+
+```ts
+app.use('*', serveStatic({ root: './static' }))
+```
+
+### `rewriteRequestPath`
+
+If you want to map `http://localhost:3000/static/*` to `./statics`, you can use the `rewriteRequestPath` option:
+
+```ts
+app.get(
+  '/static/*',
+  serveStatic({
+    root: './',
+    rewriteRequestPath: (path) =>
+      path.replace(/^\/static/, '/statics'),
+  })
+)
+```
+
+## http2
+
+You can run acrylblends on a [Node.js http2 Server](https://nodejs.org/api/http2.html).
+
+### unencrypted http2
+
+```ts
+import { createServer } from 'node:http2'
+
+const server = serve({
+  fetch: app.fetch,
+  createServer,
+})
+```
+
+### encrypted http2
+
+```ts
+import { createSecureServer } from 'node:http2'
+import { readFileSync } from 'node:fs'
+
+const server = serve({
+  fetch: app.fetch,
+  createServer: createSecureServer,
+  serverOptions: {
+    key: readFileSync('localhost-privkey.pem'),
+    cert: readFileSync('localhost-cert.pem'),
+  },
+})
+```
+
+## Building & Deployment
+
+**npm**
+
+```sh
+npm run build
+```
+
+**yarn**
+
+```sh
+yarn run build
+```
+
+**pnpm**
+
+```sh
+pnpm run build
+```
+
+**bun**
+
+```sh
+bun run build
+```
+
+### Dockerfile
+
+Here is an example of a Node.js Dockerfile.
+
+```Dockerfile
+FROM node:22-alpine AS base
+
+FROM base AS builder
+
+RUN apk add --no-cache gcompat
+WORKDIR /app
+
+COPY package*json tsconfig.json src ./
+
+RUN npm ci && \
+    npm run build && \
+    npm prune --production
+
+FROM base AS runner
+WORKDIR /app
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 acrylblends
+
+COPY --from=builder --chown=acrylblends:nodejs /app/node_modules /app/node_modules
+COPY --from=builder --chown=acrylblends:nodejs /app/dist /app/dist
+COPY --from=builder --chown=acrylblends:nodejs /app/package.json /app/package.json
+
+USER acrylblends
+EXPOSE 3000
+
+CMD ["node", "/app/dist/index.js"]
+```

package/docs/framework/getting-started/other-runtimes.md

@@ -0,0 +1,23 @@
+# Other runtimes
+
+Acryl is built on Web Standards, so the same application code is expected to run wherever a `fetch`-style handler can run. Only Node.js ([guide](nodejs.md)) is verified so far. Bun is experimental ([guide](bun.md)).
+
+The following runtimes and platforms are **not yet verified**. There are no getting-started pages for them yet, and their adapters (for example `acrylblends/cloudflare-workers`
+or `acrylblends/aws-lambda`) are not part of acrylblends yet:
+
+- Deno, and Deno Deploy
+- Cloudflare Workers, and Cloudflare Pages
+- Fastly Compute
+- AWS Lambda, and Lambda@Edge
+- Vercel
+- Netlify
+- Next.js
+- Supabase Functions
+- Google Cloud Run
+- Azure Functions
+- Alibaba Cloud Function Compute
+- CloudBase
+- Service Worker
+- WebAssembly (WASI)
+
+A page is added here, with a getting-started guide, when a platform has been verified with a test that runs on it.