Skip to main content
Deno driving a lemon car

Fresh 1.2 – welcoming a full-time maintainer, sharing state between islands, limited npm support, and more

Product UpdateFresh

It’s been almost a year since we introduced Fresh 1.0, a modern, Deno-first, edge-native full stack web framework. It embraces modern developments in tooling and progressive enhancement, using server-side just-in-time rendering and client hydration using islands. Fresh sends 0KB of JavaScript to the client by default. Since last year, Fresh has seen tremendous growth, becoming one of the top starred frontend projects in GitHub.

However, there’s been one elephant in the room - is Fresh something that the Deno team is actually committed to maintaining? When you’ve asked, we’ve always said “Yes!”, but reality was more complicated. We started April with over 60 open (and unreviewed) pull requests on the Fresh repo - we were not keeping up with maintenance to the level you’re used to from the Deno runtime project. A lot of this boiled down to me not having enough time to focus on Fresh.

We saw the first signs of this around the end of last year - so we started looking for someone to replace me as the primary maintainer of Fresh. Long story short, find we did. I’m ecstatic to announce that Marvin Hagemeister has joined the Deno company and will lead the Fresh project full-time moving forward. In case you don’t already know who Marvin is: he is a maintainer of Preact, builder of Preact DevTools, and speeder upper of the JavaScript ecosystem (just this year he sped up npm scripts from 400ms overhead to 22ms!). Give him a follow if you haven’t already.

The future of Fresh looks brighter than ever. In the coming months, you can expect significant improvements to usability, features, performance, and project maintenance. We’re still working out the exact roadmap for our plans going forward, which we’ll share once it’s ready.

For now, let’s dive into the highlight features of Fresh 1.2:

To create a new Fresh project, run:

$ deno run -A -r https://fresh.deno.dev my-app

To update your project to the latest version of Fresh, run the update script from the root of your project:

$ deno run -A -r https://fresh.deno.dev/update .

Don’t have Deno installed yet? Install it now.

Passing signals, Uint8Arrays, and circular data in island props

At the core of Fresh’s design are islands: individual components rendered on both server and client. (All other JSX in Fresh is just rendered on the server.) To make it easy to “resume” with the client render after performing the initial server render, users can pass props to islands, just like they can with all other components.

Starting today, users can pass circular objects, Uint8Array, or Preact Signals to islands in addition to all existing JSON serializable values. This unlocks a bunch of new use cases, such as passing the same signal to multiple islands and using that signal to share state between these islands:

// routes/index.tsx
import { useSignal } from "@preact/signals";
import Header from "../islands/Header.tsx";
import AddToCart from "../islands/AddToCart.tsx";

export default function Page() {
  const cart = useSignal<string[]>([]);
  return (
    <div>
      <Header cart={cart} />
      <div>
        <h1>Lemon</h1>
        <p>A very fresh fruit.</p>
        <AddToCart cart={cart} id="lemon" />
      </div>
    </div>
  );
}

// islands/Header.tsx
import { Signal } from "@preact/signals";

export default function Header(props: { cart: Signal<string[]> }) {
  return (
    <header>
      <span>Fruit Store</span>
      <button>Open cart ({props.cart.value.length})</button>
    </header>
  );
}

// islands/AddToCart.tsx
import { Signal } from "@preact/signals";

export default function AddToCart(props: {
  cart: Signal<string[]>;
  id: string;
}) {
  function add() {
    props.cart.value = [...props.cart.value, id];
  }
  return <button onClick={add}>Add to cart</button>;
}

Up to now, the props passed to islands had to be JSON serializable so they could be serialized on the server, sent to the client over HTTP, and deserialized in the browser. This JSON serialization meant that many kinds of objects could not be serialized: for example circular structures, Uint8Array, or Preact Signals.

Passing JSX to islands and nesting islands within each other

To do one better, we added support for passing JSX children to islands. They can even be nested within each other, if you desire. This allows you to mix dynamic and static parts in a way that’s best for your app.

// file: /route/index.tsx
import MyIsland from "../islands/my-island.tsx";

export default function Home() {
  return (
    <MyIsland>
      <p>This text is rendered on the server</p>
    </MyIsland>
  );
}

In the browser, we can deduce that the <p>-element was passed as children to the MyIsland from the HTML alone. This keeps your site lean and lightweight, because we don’t need any additional information other than the HTML that we need to render anyway.

Similarily, we now detect when you nest an island within another one. Whenever that occurs, we’ll treat the inner island like a standard Preact component.

// file: /route/index.tsx
import MyIsland from "../islands/my-island.tsx";
import OtherIsland from "../islands/other-island.tsx";

export default function Home() {
  return (
    <MyIsland>
      <OtherIsland>
        <p>This text is rendered on the server</p>
      </OtherIsland>
    </MyIsland>
  );
}

In the future, we’re hoping to experiment more with allowing nested islands to be lazily initialized instead. So stay tuned!

If you’re interested in the internal implementation details we recommend you to check out the pull request that made it possible: https://github.com/denoland/fresh/pull/1285 .

Limited support for npm: specifiers

Importing npm: packages is now supported in Fresh, both during server rendering and for islands. No local node_modules/ folder is required to use npm: specifiers — just like you are used to from Deno.

// routes/api/is_number.tsx
import isNumber from "npm:is-number";

export const handler = {
  async GET(req) {
    const input = await req.json();
    return Response.json(isNumber(input));
  },
};

Note that Deno Deploy does not currently support npm: specifiers, so they can not be used when deploying Fresh applications to Deno Deploy. You can expect support for npm: specifiers in Deno Deploy soon. For now, you can use npm: specifiers when deploying Fresh to a VPS or via Docker to a service like Fly.io.

Support for custom HEAD handlers

It’s now possible to declare a handler for HEAD requests in routes. Previously, routes used a default implementation with a GET handler for HEAD requests, omitting the body. This behaviour still works, but can be overridden by passing a custom function for HEAD requests.

// routes/files/:id.tsx
export const handler = {
  async HEAD(_req, ctx) {
    const headers = await fileHeaders(ctx.params.id);
    return new Response(null, { headers });
  },
  async GET(_req, ctx) {
    const headers = await fileHeaders(ctx.params.id);
    const body = await fileBody(ctx.params.id);
    return new Response(body, { headers });
  },
};

Thank you to Kamil Ogórek for the contribution.

Status and header override for HandlerContext.render

It’s now possible to set the status and headers of a Response created via ctx.render — for example, if you’d like to respond with an HTML page that has status code 400, you can now do:

// routes/index.ts
export const handler = {
  async GET(req, ctx) {
    const url = new URL(req.url);
    const user = url.searchParams.get("user");
    if (!user) {
      return ctx.render(null, {
        status: 400,
        headers: { "x-error": "missing user" },
      });
    }
    return ctx.render(user);
  },
};

Subdirectories in the ./islands folder

Previously, all islands had to declared in files directly inside of the ./islands directory. Now, they can be contained in folders inside of the ./islands directory.

// Always valid:
// islands/Counter.tsx
// islands/add_to_cart.tsx

// Newly valid:
// islands/cart/add.tsx
// islands/header/AccountPicker.tsx

Thank you Asher Gomez for adding this feature.

Async plugin rendering

Fresh supports plugins, which can customize how a page is rendered. For example, the Twind plugin extracts Tailwind CSS classes out of the rendered page and generates a CSS style sheet for these classes.

So far these “render hooks” had to be synchronous. However, some use cases (like using UnoCSS) require async “render hooks”. Now, Fresh supports an renderAsync hook.

See the documentation for information on using the renderAsync hook: https://fresh.deno.dev/docs/concepts/plugins#hook-renderasync.

Thank you Tom for adding this to fresh.

Simplified testing of Fresh projects

$fresh/server.ts now exports a new createHandler function that can be used to create a handler function from your Fresh manifest that can be used for testing.

import { createHandler } from "$fresh/server.ts";
import manifest from "../fresh.gen.ts";
import { assert, assertEquals } from "$std/testing/asserts.ts";

Deno.test("/ serves HTML", async () => {
  const handler = await createHandler(manifest);

  const resp = await handler(new Request("http://127.0.0.1/"));
  assertEquals(resp.status, 200);
  assertEquals(resp.headers.get("content-type"), "text/html; charset=utf-8");
});

Read more on writing tests for Fresh projects in the docs: https://fresh.deno.dev/docs/examples/writing-tests

Thank you to Octo8080X for making testing easier.

What’s next

We’re thrilled to have a full-time maintainer to improve and grow Fresh. As always, if you have any questions, please let us know in Discord.

Don’t miss any updates — follow us on Twitter!