Docs/Framework differences

Preact

Nexy renders Preact 10 components on the server, then Preact takes them over in the browser. Pages, layouts, islands and actions are the same in every framework: this page covers setup, then the parts that differ from the shared contracts.

Start a project

nx new my-app --template web-fbr-preact

nx new my-app --template web-modular-preact

The template is a server-mode project with Preact islands. Run nx new my-app without a template to answer the prompts instead: the router, the project type, whether to use client-side routing, then the framework.

Enable Preact in an existing project

from nexy.core.models import NexyConfigModelfrom nexy.frontend import preact  class NexyConfig(NexyConfigModel):    useFF = preact()    useAliases = {"@": "src"}

import { defineConfig } from "vite";import preact from "@preact/preset-vite";import nexy from "./__nexy__/vite"; export default defineConfig({  plugins: [nexy(), preact()],  customLogger: nexy.log(),});

nx new writes this file; Nexy writes __nexy__/vite.ts itself, so do not edit it.

Write Preact

A Preact component is a React-style function. The differences that matter here:

import { useState } from "preact/hooks"; export default function Counter({ start = 0 }: { start?: number }) {  const [count, setCount] = useState(start);  return <button class="counter" onClick={() => setCount(count + 1)}>{count}</button>;}

• Hooks come from preact/hooks, types such as ComponentChildren from preact.
• Write HTML attributes: class, for, charset. Link reads its classes from class.

Rules

• One framework per project. useFF takes exactly one framework; useFF = [preact(), react()] stops the server at startup. With useFF = preact(), every .tsx file is Preact.

• An .mdx page imports from "preact". Nexy compiles an .mdx file with Preact only when it sees that import, for example import { h } from "preact", and with React otherwise. See Markdown and MDX.

export default function Home() {  return <h1>Hello</h1>;}

import { useParams } from "@nexy/client"; export default function Post() {  const { slug } = useParams<{ slug: string }>();  return <h1>{slug}</h1>;}

import type { ComponentChildren } from "preact"; export default function RootLayout({ children }: { children: ComponentChildren }) {  return (    <html>      <body>        <header>My app</header>        <main>{children}</main>      </body>    </html>  );}

Islands

In server mode, a Preact component imported into a .nexy file is an island.

Importing

Import components in the frontmatter of the .nexy file:

---from "@/components/Counter.tsx" import Counter---<Counter start=3 />

---from "@/components/Counter.tsx" import Counter---<Counter start=3 />

Hydration directives

Use the directive prop to control when the island hydrates:

• client:load (default): immediately
• client:idle: when the browser is idle
• client:visible: when it scrolls into view
• client:media: when the media query matches

Actions and navigation

Calling actions

Use the useAction hook to manage the state of an action call:

import { useAction } from "@nexy/client";import { add_todo } from "@nexy/actions"; const { run, pending, error, data } = useAction(add_todo);// ...<button onClick={() => run({ title: "New Task" })}>Add</button>

Navigation

Use the Link component for client-side transitions. Note that Preact uses class instead of className:

import { Link } from "@nexy/client"; <Link href="/about" class="nav" activeClassName="active">About</Link>

For programmatic navigation, use the useRouter hook:

import { useRouter } from "@nexy/client"; const router = useRouter();router.push("/dashboard");

URL access

• usePathname(): current path
• useParams(): dynamic segments
• useSearchParams(): query string
• useLocation(): full location object

Next steps

• Views: compare the formats a page can use
• Frontend: Vite and the client build

Copy page as Markdown Edit on GitHub