create-acrylblends 0.0.0-stage → 0.1.0

package/docs/framework/guides/best-practices.md

@@ -0,0 +1,231 @@
+# Best Practices
+
+Acryl is very flexible. You can write your app as you like.
+However, there are best practices that are better to follow.
+
+## Don't make "Controllers" when possible
+
+When possible, you should not create "Ruby on Rails-like Controllers".
+
+```ts
+// 🙁
+// A RoR-like Controller
+const booksList = (c: Context) => {
+  return c.json('list books')
+}
+
+app.get('/books', booksList)
+```
+
+The issue is related to types. For example, the path parameter cannot be inferred in the Controller without writing complex generics.
+
+```ts
+// 🙁
+// A RoR-like Controller
+const bookPermalink = (c: Context) => {
+  const id = c.req.param('id') // Can't infer the path param
+  return c.json(`get ${id}`)
+}
+```
+
+Therefore, you don't need to create RoR-like controllers and should write handlers directly after path definitions.
+
+```ts
+// 😃
+app.get('/books/:id', (c) => {
+  const id = c.req.param('id') // Can infer the path param
+  return c.json(`get ${id}`)
+})
+```
+
+## `factory.createHandlers()` in `acrylblends/factory`
+
+If you still want to create a RoR-like Controller, use `factory.createHandlers()` in [`acrylblends/factory`](../helpers/factory.md). If you use this, type inference will work correctly.
+
+```ts
+import { createFactory } from 'acrylblends/factory'
+import { logger } from 'acrylblends/logger'
+
+declare module 'acrylblends' {
+  interface ContextVariableMap {
+    foo: string
+  }
+}
+
+// ...
+
+// 😃
+const factory = createFactory()
+
+const middleware = factory.createMiddleware(async (c, next) => {
+  c.set('foo', 'bar')
+  await next()
+})
+
+const handlers = factory.createHandlers(logger(), middleware, (c) => {
+  return c.json(c.var.foo)
+})
+
+app.get('/api', ...handlers)
+```
+
+## Building a larger application
+
+Use `app.route()` to build a larger application without creating "Ruby on Rails-like Controllers".
+
+If your application has `/authors` and `/books` endpoints and you wish to separate files from `index.ts`, create `authors.ts` and `books.ts`.
+
+```ts
+// authors.ts
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.get('/', (c) => c.json('list authors'))
+app.post('/', (c) => c.json('create an author', 201))
+app.get('/:id', (c) => c.json(`get ${c.req.param('id')}`))
+
+export default app
+```
+
+```ts
+// books.ts
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.get('/', (c) => c.json('list books'))
+app.post('/', (c) => c.json('create a book', 201))
+app.get('/:id', (c) => c.json(`get ${c.req.param('id')}`))
+
+export default app
+```
+
+Then, import them and mount on the paths `/authors` and `/books` with `app.route()`.
+
+```ts
+// index.ts
+import { Acryl } from 'acrylblends'
+import authors from './authors'
+import books from './books'
+
+const app = new Acryl()
+
+// 😃
+app.route('/authors', authors)
+app.route('/books', books)
+
+export default app
+```
+
+### If you want to use RPC features
+
+The code above works well for normal use cases.
+However, if you want to use the `RPC` feature, you can get the correct type by chaining as follows.
+
+```ts
+// authors.ts
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+  .get('/', (c) => c.json('list authors'))
+  .post('/', (c) => c.json('create an author', 201))
+  .get('/:id', (c) => c.json(`get ${c.req.param('id')}`))
+
+export default app
+export type AppType = typeof app
+```
+
+If you pass the type of the `app` to `hc`, it will get the correct type.
+
+```ts
+import type { AppType } from './authors'
+import { hc } from 'acrylblends/client'
+
+// 😃
+const client = hc<AppType>('http://localhost') // Typed correctly
+```
+
+For more detailed information, please see [the RPC page](rpc.md#using-rpc-with-larger-applications).
+
+## HEAD Request Best Practices
+
+### Understanding Acryl's HEAD Handling
+
+Acryl automatically handles HEAD requests by converting them to GET requests and stripping the response body. This behavior is built into the framework's dispatch layer and happens before route matching occurs.
+
+### ✅ Do: Use GET Routes for HEAD Requests
+
+```ts
+// GOOD: This GET route automatically handles HEAD requests
+app.get('/api/users', async (c) => {
+  const users = await getUsers()
+  c.header('X-Total-Count', users.length.toString())
+  return c.json(users)
+})
+
+// HEAD /api/users will return:
+// - Same headers as GET (including X-Total-Count)
+// - Status 200
+// - No body (null)
+```
+
+### ✅ Do: Use Middleware for HEAD-Specific Logic
+
+```ts
+// GOOD: Use middleware when HEAD needs different behavior
+app.use('/api/resource', async (c, next) => {
+  await next()
+
+  // Add HEAD-specific headers after the handler
+  if (c.req.method === 'HEAD') {
+    c.header('X-HEAD-Processed', 'true')
+    // Don't compute expensive body content for HEAD
+    c.res = new Response(null, c.res)
+  }
+})
+```
+
+### ❌ Don't: Try to Create Dedicated HEAD Handlers
+
+```ts
+// BAD: This won't work as expected
+app.head('/api/users', (c) => {
+  // This handler will NEVER be called
+  c.header('X-Custom', 'value')
+  return c.text('ignored')
+})
+
+// BAD: Using on() also won't work
+app.on('HEAD', '/api/users', (c) => {
+  // Still converted to GET before route matching
+})
+```
+
+### Performance Considerations
+
+- **Avoid expensive operations in GET handlers if you expect many HEAD requests**: Use middleware to detect HEAD and skip body generation
+- **Cache headers work identically**: HEAD responses respect the same caching rules as GET
+- **Middleware compatibility**: Most middleware works with HEAD, but body-processing middleware (like compression) automatically skips HEAD requests
+
+### Testing HEAD Requests
+
+```ts
+// Always test both GET and HEAD responses
+it('handles HEAD requests correctly', async () => {
+  const getRes = await app.request('/api/users')
+  const headRes = await app.request('/api/users', { method: 'HEAD' })
+
+  expect(headRes.status).toBe(getRes.status)
+  expect(headRes.headers.get('X-Total-Count')).toBe(
+    getRes.headers.get('X-Total-Count')
+  )
+  expect(headRes.body).toBe(null)
+})
+```
+
+### Notes
+
+- The automatic HEAD conversion ensures consistent headers between GET and HEAD responses
+- This behavior is consistent across all Acryl runtimes (Node.js, Bun)
+- If you need completely different logic for HEAD vs GET, consider using different endpoints rather than trying to override the framework's HEAD handling

package/docs/framework/guides/create-acrylblends.md

@@ -0,0 +1,79 @@
+# create-acrylblends
+
+`create-acrylblends` is the project initializer that runs when you run `npm create acrylblends@latest`, `npx create-acrylblends@latest`, `pnpm create acrylblends@latest`,
+`yarn create acrylblends` or `bun create acrylblends@latest`. It creates a folder with a working Acryl application for the runtime you choose.
+
+## Templates
+
+| Template | What you get |
+| --- | --- |
+| `nodejs` | an Acryl application served with `serve()` from `acrylblends/node-server`; run with Node.js 22.19 or newer |
+| `bun` (experimental) | an Acryl application with `export default app`, run with `bun` |
+| `acryl-app` | a Cordis app built from plugins, with an agent that can extend it while it runs (the same app `npx acrylblends init --template agent` creates) |
+
+Every template includes `AGENTS.md` and `CLAUDE.md` (which imports `AGENTS.md`) and a copy of these docs in `docs/framework/`, so a coding agent working in the folder reads the
+API from the folder.
+
+## Passing arguments
+
+When you use `npm create` (or `npx`), arguments meant for the initializer must be placed **after** `--`. Anything after `--` is forwarded to the initializer.
+
+**npm**
+
+```sh
+npm create acrylblends@latest my-app -- --template nodejs
+```
+
+**yarn**
+
+```sh
+yarn create acrylblends my-app --template nodejs
+```
+
+**pnpm**
+
+```sh
+pnpm create acrylblends@latest my-app --template nodejs
+```
+
+**bun**
+
+```sh
+bun create acrylblends@latest my-app --template nodejs
+```
+
+## Arguments
+
+| Argument | Description | Example |
+| :-- | :-- | :-- |
+| `[directory]` | The folder to create. It must not exist or must be empty. Asked for when it is missing. | `my-app` |
+| `--template <template>` | One of `nodejs`, `bun` (experimental), `acryl-app`. Skips the template question. | `--template bun` |
+| `--install` | Install the dependencies with the package manager after creating the project. | `--install` |
+| `--pm <packageManager>` | The package manager for `--install`: `npm`, `pnpm`, `yarn` or `bun`. Defaults to the one that started the initializer. | `--pm pnpm` |
+| `--yes`, `-y` | Ask nothing: use `nodejs` unless `--template` is given, and the directory `acryl-app`. | `-y` |
+| `--help` | Print the arguments. | `--help` |
+
+The templates are inside the package, so creating a project needs no network except for `--install`.
+
+## Example flows
+
+### Interactive
+
+```sh
+npm create acrylblends@latest my-app
+```
+
+This asks which template you want.
+
+### Non-interactive
+
+```sh
+npm create acrylblends@latest my-app -- --template nodejs --pm npm --install
+```
+
+This creates `my-app` from the `nodejs` template and installs its dependencies with npm.
+
+## Troubleshooting
+
+- If an argument is not recognized, make sure you forward it with `--` when you use `npm create` or `npx`.
+- Run `npm create acrylblends@latest -- --help` to see the arguments of the version you have.

package/docs/framework/guides/examples.md

@@ -0,0 +1,3 @@
+# Examples
+
+See the Examples section.

package/docs/framework/guides/faq.md

@@ -0,0 +1,19 @@
+# Frequently Asked Questions
+
+## Why does `/orders/` return 404 when `/orders` works?
+
+Trailing slashes are strict by default: `/orders` and `/orders/` are different paths. Add `trimTrailingSlash()` to redirect, or set the router to ignore the slash. See
+[Mounting and trailing slashes](../cordis/mounting.md#trailing-slashes).
+
+## Why does my validator see `{}` for a JSON body?
+
+A `json` validation target reads the body only when the request has a JSON `Content-Type`; without it the validator sees `{}`. See
+[Validation with Standard Schema](../cordis/validation.md).
+
+## Which runtimes are verified?
+
+Node.js. Bun is experimental. The others are listed, as not yet verified, on [Other runtimes](../getting-started/other-runtimes.md).
+
+## Where are the parts marked "not yet available"?
+
+Their pages are part of the documentation so that the structure is complete; each starts with a note saying so. They are enabled as they are ported.

package/docs/framework/guides/helpers.md

@@ -0,0 +1,33 @@
+# Helpers
+
+Helpers are available to assist in developing your application. Unlike middleware, they don't act as handlers, but rather provide useful functions.
+
+For instance, here's how to use the [Cookie helper](../helpers/cookie.md):
+
+```ts
+import { getCookie, setCookie } from 'acrylblends/cookie'
+
+const app = new Acryl()
+
+app.get('/cookie', (c) => {
+  const yummyCookie = getCookie(c, 'yummy_cookie')
+  // ...
+  setCookie(c, 'delicious_cookie', 'macha')
+  //
+})
+```
+
+## Available Helpers
+
+- [Accepts](../helpers/accepts.md)
+- [Adapter](../helpers/adapter.md)
+- [Cookie](../helpers/cookie.md)
+- [css](../helpers/css.md)
+- [Dev](../helpers/dev.md)
+- [Factory](../helpers/factory.md)
+- [html](../helpers/html.md)
+- [JWT](../helpers/jwt.md)
+- [SSG](../helpers/ssg.md)
+- [Streaming](../helpers/streaming.md)
+- [Testing](../helpers/testing.md)
+- [WebSocket](../helpers/websocket.md)

package/docs/framework/guides/jsx-dom.md

@@ -0,0 +1,299 @@
+# Client Components
+
+> **Not yet available.** The client-side JSX package (`acrylblends/jsx/dom`) is documented here so the page structure matches the rest of the framework, and is not part of acrylblends yet. The code on this page is not checked by the docs tests.
+
+
+`acrylblends/jsx` supports not only server side but also client side. This means that it is possible to create an interactive UI that runs in the browser. We call it Client Components or `acrylblends/jsx/dom`.
+
+It is fast and very small. The counter program in `acrylblends/jsx/dom` is only 2.8KB with Brotli compression, but 47.8KB for React.
+
+This section introduces Client Components-specific features.
+
+## Counter example
+
+Here is an example of a simple counter, the same code works as in React.
+
+```tsx
+import { useState } from 'acrylblends/jsx'
+import { render } from 'acrylblends/jsx/dom'
+
+function Counter() {
+  const [count, setCount] = useState(0)
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={() => setCount(count + 1)}>Increment</button>
+    </div>
+  )
+}
+
+function App() {
+  return (
+    <html>
+      <body>
+        <Counter />
+      </body>
+    </html>
+  )
+}
+
+const root = document.getElementById('root')
+render(<App />, root)
+```
+
+## `render()`
+
+You can use `render()` to insert JSX components within a specified HTML element.
+
+```tsx
+render(<Component />, container)
+```
+
+You can see full example code here: Counter example.
+
+## Hooks compatible with React
+
+acrylblends/jsx/dom has Hooks that are compatible or partially compatible with React. You can learn about these APIs by looking at [the React documentation](https://react.dev/reference/react/hooks).
+
+- `useState()`
+- `useEffect()`
+- `useRef()`
+- `useCallback()`
+- `use()`
+- `startTransition()`
+- `useTransition()`
+- `useDeferredValue()`
+- `useMemo()`
+- `useLayoutEffect()`
+- `useReducer()`
+- `useDebugValue()`
+- `createElement()`
+- `memo()`
+- `isValidElement()`
+- `useId()`
+- `createRef()`
+- `forwardRef()`
+- `useImperativeHandle()`
+- `useSyncExternalStore()`
+- `useInsertionEffect()`
+- `useFormStatus()`
+- `useActionState()`
+- `useOptimistic()`
+
+## `startViewTransition()` family
+
+The `startViewTransition()` family contains original hooks and functions to handle [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) easily. The examples below demonstrate how to use them.
+
+### 1. A very simple example
+
+You can write a transition using the `document.startViewTransition` shortly with the `startViewTransition()`.
+
+```tsx
+import { useState, startViewTransition } from 'acrylblends/jsx'
+import { css, Style } from 'acrylblends/css'
+
+export default function App() {
+  const [showLargeImage, setShowLargeImage] = useState(false)
+  return (
+    <>
+      <Style />
+      <button
+        onClick={() =>
+          startViewTransition(() =>
+            setShowLargeImage((state) => !state)
+          )
+        }
+      >
+        Click!
+      </button>
+      <div>
+        {!showLargeImage ? (
+          <img src=' />
+        ) : (
+          <div
+            class={css`
+              background: url(');
+              background-size: contain;
+              background-repeat: no-repeat;
+              background-position: center;
+              width: 600px;
+              height: 600px;
+            `}
+          ></div>
+        )}
+      </div>
+    </>
+  )
+}
+```
+
+### 2. Using `viewTransition()` with `keyframes()`
+
+The `viewTransition()` function allows you to get the unique `view-transition-name`.
+
+You can use it with the `keyframes()`, The `::view-transition-old()` is converted to `::view-transition-old(${uniqueName))`.
+
+```tsx
+import { useState, startViewTransition } from 'acrylblends/jsx'
+import { viewTransition } from 'acrylblends/jsx/dom/css'
+import { css, keyframes, Style } from 'acrylblends/css'
+
+const rotate = keyframes`
+  from {
+    rotate: 0deg;
+  }
+  to {
+    rotate: 360deg;
+  }
+`
+
+export default function App() {
+  const [showLargeImage, setShowLargeImage] = useState(false)
+  const [transitionNameClass] = useState(() =>
+    viewTransition(css`
+      ::view-transition-old() {
+        animation-name: ${rotate};
+      }
+      ::view-transition-new() {
+        animation-name: ${rotate};
+      }
+    `)
+  )
+  return (
+    <>
+      <Style />
+      <button
+        onClick={() =>
+          startViewTransition(() =>
+            setShowLargeImage((state) => !state)
+          )
+        }
+      >
+        Click!
+      </button>
+      <div>
+        {!showLargeImage ? (
+          <img src=' />
+        ) : (
+          <div
+            class={css`
+              ${transitionNameClass}
+              background: url(');
+              background-size: contain;
+              background-repeat: no-repeat;
+              background-position: center;
+              width: 600px;
+              height: 600px;
+            `}
+          ></div>
+        )}
+      </div>
+    </>
+  )
+}
+```
+
+### 3. Using `useViewTransition`
+
+If you want to change the style only during the animation. You can use `useViewTransition()`. This hook returns the `[boolean, (callback: () => void) => void]`, and they are the `isUpdating` flag and the `startViewTransition()` function.
+
+When this hook is used, the Component is evaluated at the following two times.
+
+- Inside the callback of a call to `startViewTransition()`.
+- When [the `finish` promise becomes fulfilled](https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition/finished)
+
+```tsx
+import { useState, useViewTransition } from 'acrylblends/jsx'
+import { viewTransition } from 'acrylblends/jsx/dom/css'
+import { css, keyframes, Style } from 'acrylblends/css'
+
+const rotate = keyframes`
+  from {
+    rotate: 0deg;
+  }
+  to {
+    rotate: 360deg;
+  }
+`
+
+export default function App() {
+  const [isUpdating, startViewTransition] = useViewTransition()
+  const [showLargeImage, setShowLargeImage] = useState(false)
+  const [transitionNameClass] = useState(() =>
+    viewTransition(css`
+      ::view-transition-old() {
+        animation-name: ${rotate};
+      }
+      ::view-transition-new() {
+        animation-name: ${rotate};
+      }
+    `)
+  )
+  return (
+    <>
+      <Style />
+      <button
+        onClick={() =>
+          startViewTransition(() =>
+            setShowLargeImage((state) => !state)
+          )
+        }
+      >
+        Click!
+      </button>
+      <div>
+        {!showLargeImage ? (
+          <img src=' />
+        ) : (
+          <div
+            class={css`
+              ${transitionNameClass}
+              background: url(');
+              background-size: contain;
+              background-repeat: no-repeat;
+              background-position: center;
+              width: 600px;
+              height: 600px;
+              position: relative;
+              ${isUpdating &&
+              css`
+                &:before {
+                  content: 'Loading...';
+                  position: absolute;
+                  top: 50%;
+                  left: 50%;
+                }
+              `}
+            `}
+          ></div>
+        )}
+      </div>
+    </>
+  )
+}
+```
+
+## The `acrylblends/jsx/dom` runtime
+
+There is a small JSX Runtime for Client Components. Using this will result in smaller bundled results than using `acrylblends/jsx`. Specify `acrylblends/jsx/dom` in `tsconfig.json`. For Deno, modify the deno.json.
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "acrylblends/jsx/dom"
+  }
+}
+```
+
+Alternatively, you can specify `acrylblends/jsx/dom` in the esbuild transform options in `vite.config.ts`.
+
+```ts
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  esbuild: {
+    jsxImportSource: 'acrylblends/jsx/dom',
+  },
+})
+```