denoland / fresh

The next-gen web framework.

Documentation | Getting started | API Reference

fresh

Fresh is a next generation web framework, built for speed, reliability, and simplicity.

Some stand-out features:

• Just-in-time rendering on the edge.
• Island based client hydration for maximum interactivity.
• Zero runtime overhead: no JS is shipped to the client by default.
• No build step.
• No configuration necessary.
• TypeScript support out of the box.
• File-system routing à la Next.js.

📖 Documentation

The documentation is available on fresh.deno.dev.

🚀 Getting started

Install the latest Deno CLI version.

You can scaffold a new project by running the Fresh init script. To scaffold a project run the following:

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

Then navigate to the newly created project folder:

cd deno-fresh-demo

From within your project folder, start the development server using the deno task command:

deno task start

Now open http://localhost:8000 in your browser to view the page. You make changes to the project source code and see them reflected in your browser.

To deploy the project to the live internet, you can use Deno Deploy:

1. Push your project to GitHub.
2. Create a Deno Deploy project.
3. Link the Deno Deploy project to the main.ts file in the root of the created repository.
4. The project will be deployed to a public $project.deno.dev subdomain.

For a more in-depth getting started guide, visit the Getting Started page in the Fresh docs.

Contributing

We appreciate your help! To contribute, please read our contributing instructions.

Adding your project to the showcase

If you feel that your project would be helpful to other Fresh users, please consider putting your project on the showcase. However, websites that are just for promotional purposes may not be listed.

To take a screenshot, run the following command.

deno task screenshot [url] [your-app-name]

Then add your site to showcase.json, preferably with source code on GitHub, but not required.

Badges

[![Made with Fresh](https://fresh.deno.dev/fresh-badge.svg)](https://fresh.deno.dev)

<a href="https://fresh.deno.dev">
  <img
    width="197"
    height="37"
    src="https://fresh.deno.dev/fresh-badge.svg"
    alt="Made with Fresh"
  />
</a>

[![Made with Fresh](https://fresh.deno.dev/fresh-badge-dark.svg)](https://fresh.deno.dev)

<a href="https://fresh.deno.dev">
  <img
    width="197"
    height="37"
    src="https://fresh.deno.dev/fresh-badge-dark.svg"
    alt="Made with Fresh"
  />
</a>

Hashtags

Use the following hashtags in your social media posts that reference Fresh and as Topics in the About section of your GitHub repos that contain Fresh code. It will assure maximum visibility for your posts and code, and promote Fresh development ecosystem visibility.

• #denofresh
• #deno

Github repo Topics will not include the hash symbol.

fresh's Issues

Add "Head" component

To add tags to the head from via any component.

404 not found

hi!, I wanted to try fresh, but appear me that when i want to installed from deno

Change handler signature from `(ctx) => resp` to `(req, ctx) => resp`

The current signature is somewhat clumsy. It does not align nicely with the signature for serve from deno.land/std.

The req property from ctx should be removed. The match property from ctx should be renamed to params.

This is a prerequisite for #96.

Cannot find name 'URLPattern'

This error occurs intermittently when running my server:

Download https://deno.land/[email protected]/_util/assert.ts
Download https://cdn.esm.sh/v56/[email protected]/src/index.d.ts
Download https://cdn.esm.sh/v56/[email protected]/src/jsx.d.ts
Download https://crux.land/api/get/2KNRVU.ts
Check file:///Users/quenio/Projects/LiteTrade/indiepro/main.ts
error: TS2304 [ERROR]: Cannot find name 'URLPattern'.
        const pattern = new URLPattern({
                            ~~~~~~~~~~
    at https://crux.land/api/get/2KNRVU.ts:136:29
Watcher Process finished. Restarting on file change...

My deps_client.ts:

/// <reference no-default-lib="true" />
/// <reference lib="dom" />
/// <reference lib="dom.asynciterable" />
/// <reference lib="deno.ns" />
/// <reference lib="deno.unstable" />

export * from "https://raw.githubusercontent.com/lucacasonato/fresh/main/runtime.ts"

My deps_server.ts:

export * from "https://raw.githubusercontent.com/lucacasonato/fresh/main/server.ts"

Fresh routes error

After running fresh routes ...
the routes.gen.ts has errors 'Unable to load a local module: ' 'check file path' ...

import * as $0 from "./pagesce/pages/api/joke.ts";
import * as $1 from "./pagesce/pages/index.tsx";
import * as $2 from "./pagesce/pages/[name].tsx";

The folder 'pagesce' does not exist.
If I edit routes.gen.ts to remove (pagesce/)

import * as $0 from "./pages/api/joke.ts";
import * as $1 from "./pages/index.tsx";
import * as $2 from "./pages/[name].tsx";

the app runs without errors.

deno 1.11.4 (release, x86_64-pc-windows-msvc)
v8 9.1.269.35
typescript 4.3.2

deployctl 0.3.0

Support rewrites

This should be configurable via a rewrites key in a configuration options bag for start(). It should look pretty similar to Next.js. but more customization and less regexp.

const config = {
  rewrites: [
    {
      source: "/old-about/:path*",
      destination: "/about",
      // The :path parameter isn't used here so will be automatically passed in
      // the query.
    },
    {
      source: "/docs/:path*",
      destination: "/:path*",
      // The :path parameter is used here so will not be automatically passed in
      // the query.
    },
    {
      source: "/:first/:second",
      destination: "/:first?second=:second",
      // Since the :first parameter is used in the destination the :second
      // parameter will not automatically be added in the query although we can
      // manually add it as shown above.
    },
    {
      source: "/x/std/:path*",
      destination: ({ headers }) => {
        // If the user agent is requesting HTML data fall through the rewrite
        // (pretend it doesn't exist), else rewrite to an API route.
        if (headers.get("content-type").includes("text/html")) return null;
        return "/api/raw/std/:path*";
      },
    },
  ],
};

start(routes, config);

We could add redirect support down the line too.

Add integration test for `fresh init`

Should run the command, check that files are generated correctly, and then check that the server starts up correctly & type checks.

Caching of JIT JS bundles

JIT JS bundles need to be cached

Remove deprecated runtimeJS option

#97 makes PageConfig['runtimeJS'] irrelevant. AFAICT, it can be safely removed.

Argument of type 'URL' is not assignable to parameter of type 'string'.

on line 151 you are passing a url instead of a string

const url = new URL(req.url);
      if (url.pathname.length > 1 && url.pathname.endsWith("/")) {
        url.pathname = url.pathname.slice(0, -1);
        return Response.redirect(url, 307);
      }

probably should be:
const url = new URL(req.url);
if (url.pathname.length > 1 && url.pathname.endsWith("/")) {
url.pathname = url.pathname.slice(0, -1);
return Response.redirect(JSON.stringify(url), 307);
}

Add support for cached static asset handling

Currently, assets stored in the static/ directory in the project are served through fresh automatically. These assets are served without any cache headers though. This is not ideal (especially not for assets which rarely change). It would not be safe to just plainly add long duration cache headers, but it would be reasonable to also host static assets at a seperate URL endpoint that includes the deployment ID in the path. For that "hashed" path, it would be safe to include a very long duration cache header.

I imagine the API would look like this:

...
import { asset } from "../client_deps.ts";

function Page() {
  return <link type="stylesheet" href={asset("/style.css")} />
}

The output of the asset("/style.css") call would be something like /_frsh/static/${DEPLOYMENT_ID}/style.css. The cache header could be immutable for at least 1 year.

Show page build errors (500 errors) as a nice HTML error page during development

Currently when a page fails to render (for example it throws), an error is logged to the console and the HTTP request is responded to with a '500 Internal Server Error' response. After this plain text response is rendered in the browser, the hot-reload breaks because the reload.js script is not running in the browser anymore (because the 500 error is a plain text page, not an HTML page).

Ideally the default 500 error page should be a regular HTML page, that contains the reload.js script as usual.

One can probably do this by removing this try-catch block here: https://github.com/lucacasonato/fresh/blob/fc25d2dfbf58d3ad2f9aba4b49925b12a8abafc9/src/server/context.ts#L312-L333
and then improving the default error page here to include a component and changing the handler to be (ctx) => ctx.render():
https://github.com/lucacasonato/fresh/blob/fc25d2dfbf58d3ad2f9aba4b49925b12a8abafc9/src/server/context.ts#L506-L514

`fresh init myproject` results in an error

➜  ~ fresh init tea
error: Uncaught (in promise) TypeError: Must be an absolute path.
  if (!isAbsolute(path)) {
                      ^
    at toFileUrl (https://deno.land/[email protected]/path/posix.ts:499:23)
    at routes (file:///Users/sr/c/github.com/lucacasonato/fresh/src/cli/routes.ts:50:20)
    at async init (file:///Users/sr/c/github.com/lucacasonato/fresh/src/cli/init.ts:188:14)
    at async initSubcommand (file:///Users/sr/c/github.com/lucacasonato/fresh/src/cli/init.ts:41:32)
    at async file:///Users/sr/c/github.com/lucacasonato/fresh/cli.ts:34:14

The directory tea is created and deployctl run results in the following error.

➜  tea deployctl run --no-check --watch main.ts
error: Cannot resolve module "file:///Users/sr/tea/routes.gen.ts" from "file:///Users/sr/tea/main.ts".
    at file:///Users/sr/tea/main.ts:2:0

API functions

Should just be oak routes exported as default exports from a page under pages/api/.

On windows - Broken count buttons in the example project, and init

When trying to run the example, the count buttons are not enabled.

It seems the js script is not found.

the init script should probably have runtime: true in the generated index.tsx as well

Development address not obvious

When starting, the 0.0.0.0:8000 address appear in the terminal.

Although when navigating to it, there is nothing.
The documentation mention localhost:8080

The correct address is localhost:8000

Caching of pages

Pages should be cachable, and incrementally statically rebuildable. This should either be a hook, or an export from the page component. We should also provide an API to let the user invalidate a cached page.

Figure out how to use twind

twind can do server side JIT CSS generation with tailwind style CSS. It would be really cool to add support for that: https://twind.dev/api/modules/twind_sheets.html.

It would require letting the user hook into the render pipeline somehow - they would need to setup twind just before rendering, extract css after the rendering is done, and then inject that into an inline stylesheet. On the client the user would also load twind to dynamically create more classes when components are rendered.

Use pure "Request -> Promise<Response>" functions for api endpoints

This way people can use any library on-top of this that they want.

Elide __FRSH_PROPS if there is no `data` or `params`

Just a tiny size optimization.

Add custom render function support

The start function that starts the server in main.ts should take an optional render function. This function can be used to create the JIT server side rendered static HTML page for a specific route. It gets a page component, some items to put into the <head>, and some items to put at the end of the <body> in its parameters, and returns a string.

There is a default implementation of this render function. It can be used for advanced use-cases like #7

Consider adding service worker to do "client side routing"

This would not really be client side routing. A request to the server would still be made, but it would be differential - so for example only the body would be fetched, not the entire document with the wrapper.

Add support for custom error pages

pages/404.tsx
pages/500.tsx

Rename `HandlerContext.match` to `HandlerContext.params`

Optimized bundles

Because bundles are generated with esbuild JIT, we can optimize bundles for each browser we are serving content to. For example the bundle shipped to Firefox 88 would need transpilation for private class methods, whereas a bundle shipped to the latest Chrome would not.

Browser version can be determined by User-Agent string. The remaining question is just if this is even a good idea.

IS_BROWSER or useData tree shaking

Suppose server-side-module.ts does not work on browser.
ex: import * as xmlParser from "https://cdn.pika.dev/fast-xml-parser@^3.17.3"; works perfect on deno but fails for browser bundle.
I want to use it on serverside rendering and keep runtimeJS true.

export const config: PageConfig = { runtimeJS: true }
export default function Page () {
  const data = useData('', async ()=>{
    if(!IS_BROWSER){
      const mod = await import('server-side-module.ts')
      return mod.getVal()
    }
  })
  return <p>{data}</p>
}

I hope the import will be removed by tree shaking, but fresh will try to bundle the server-side-module.ts and fail.
Is there any better way to do this?

JS version

Do you guys plan to add a pure JS version?

expose target options

Hi there :)

Cool project. It'd be great if you could expose a way to modify the targets that esbuild uses. I have a lib that uses bigints and as a result I get this error Big integer literals are not available in the configured target environment ("chrome89", "firefox88", "safari13")

Expose source IP to middleware and handlers

unable to start project locally

Hello,
when I wanted to deploy new project with deployctl There was an error that says:

 $ ~/mySrc/myproject deployctl run --watch --no-check **main.ts**
Download https://x.lcas.dev/[email protected]/hooks.js
error: error sending request for url (https://x.lcas.dev/[email protected]/hooks.js): error trying to connect: tls handshake eof
    at https://raw.githubusercontent.com/lucacasonato/fresh/main/src/runtime/deps.ts:2:0

versions:
deno: deno 1.11.4+ed16f43
deployctl: deployctl 0.3.0
fresh: deployctl 0.1.0

Update:
I don't know why this problem fixed after running deno run main.ts (this command downloaded (https://x.lcas.dev/[email protected]/hooks.js))
then I am able to run deployctl.
but this time after opening the site in browser, deno throws error and 500 response...

Listening on http://0.0.0.0:8080
 > deno:https://raw.githubusercontent.com/lucacasonato/fresh/main/src/runtime/deps.ts:1:14: error: [plugin: deno] error sending request for url (https://x.lcas.dev/[email protected]/mod.js): error trying to connect: tls handshake eof
    1 │ export * from "https://x.lcas.dev/[email protected]/mod.js";
      ╵               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


 > deno:https://raw.githubusercontent.com/lucacasonato/fresh/main/src/runtime/deps.ts:23:7: error: [plugin: deno] error sending request for url (https://x.lcas.dev/[email protected]/hooks.js): error trying to connect: tls handshake eof
    23 │ } from "https://x.lcas.dev/[email protected]/hooks.js";
       ╵        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Error: Build failed with 2 errors:
deno:https://raw.githubusercontent.com/lucacasonato/fresh/main/src/runtime/deps.ts:1:14: error: [plugin: deno] error sending request for url (https://x.lcas.dev/[email protected]/mod.js): error trying to connect: tls handshake eof
deno:https://raw.githubusercontent.com/lucacasonato/fresh/main/src/runtime/deps.ts:23:7: error: [plugin: deno] error sending request for url (https://x.lcas.dev/[email protected]/hooks.js): error trying to connect: tls handshake eof
    at failureErrorWithLog (https://gist.githubusercontent.com/lucacasonato/358c6b7e8198bfb2cf3d220e49fdcf5f/raw/3714cb0f59606eefc29ed0fea36d4cd93549938b/esbuild-wasm.js:3052:19)
    at https://gist.githubusercontent.com/lucacasonato/358c6b7e8198bfb2cf3d220e49fdcf5f/raw/3714cb0f59606eefc29ed0fea36d4cd93549938b/esbuild-wasm.js:2734:32
    at runOnEndCallbacks (https://gist.githubusercontent.com/lucacasonato/358c6b7e8198bfb2cf3d220e49fdcf5f/raw/3714cb0f59606eefc29ed0fea36d4cd93549938b/esbuild-wasm.js:2532:51)
    at buildResponseToResult (https://gist.githubusercontent.com/lucacasonato/358c6b7e8198bfb2cf3d220e49fdcf5f/raw/3714cb0f59606eefc29ed0fea36d4cd93549938b/esbuild-wasm.js:2732:11)
    at https://gist.githubusercontent.com/lucacasonato/358c6b7e8198bfb2cf3d220e49fdcf5f/raw/3714cb0f59606eefc29ed0fea36d4cd93549938b/esbuild-wasm.js:2839:18
    at https://gist.githubusercontent.com/lucacasonato/358c6b7e8198bfb2cf3d220e49fdcf5f/raw/3714cb0f59606eefc29ed0fea36d4cd93549938b/esbuild-wasm.js:2223:13
    at handleIncomingPacket (https://gist.githubusercontent.com/lucacasonato/358c6b7e8198bfb2cf3d220e49fdcf5f/raw/3714cb0f59606eefc29ed0fea36d4cd93549938b/esbuild-wasm.js:2320:13)
    at readFromStdout (https://gist.githubusercontent.com/lucacasonato/358c6b7e8198bfb2cf3d220e49fdcf5f/raw/3714cb0f59606eefc29ed0fea36d4cd93549938b/esbuild-wasm.js:2190:11)
    at Object.worker.onmessage (https://gist.githubusercontent.com/lucacasonato/358c6b7e8198bfb2cf3d220e49fdcf5f/raw/3714cb0f59606eefc29ed0fea36d4cd93549938b/esbuild-wasm.js:3906:38)
    at https://gist.githubusercontent.com/lucacasonato/358c6b7e8198bfb2cf3d220e49fdcf5f/raw/3714cb0f59606eefc29ed0fea36d4cd93549938b/esbuild-wasm.js:3897:45

fresh init is broken

Run Fresh init, then start the server.

$ deno run -A --unstable --watch main.ts
Check file:///C:/Users/sylva/Documents/Projects/OpenSource/test_fresh/main.ts
error: TS2345 [ERROR]: Argument of type '{ pages: { "./pages/api/joke.ts": typeof $0; "./pages/index.tsx": typeof $1; "./pages/[name].tsx": typeof $2; }; baseUrl: string; }' is not assignable to parameter of type 'Routes'.
  Types of property 'pages' are incompatible.
    Type '{ "./pages/api/joke.ts": typeof $0; "./pages/index.tsx": typeof $1; "./pages/[name].tsx": typeof $2; }' is not assignable to type 'Record<string, PageModule | RendererModule>'.
      Property '"./pages/api/joke.ts"' is incompatible with index signature.
        Type 'typeof import("file:///C:/Users/sylva/Documents/Projects/OpenSource/test_fresh/pages/api/joke.ts")' is not assignable to type 'PageModule | RendererModule'.
          Type 'typeof import("file:///C:/Users/sylva/Documents/Projects/OpenSource/test_fresh/pages/api/joke.ts")' is not assignable to type 'PageModule'.
            Types of property 'handler' are incompatible.
              Type '(_req: Request) => Response' is not assignable to type 'Handler | Handlers | undefined'.
                Type '(_req: Request) => Response' is not assignable to type 'Handler'.
                  Types of parameters '_req' and 'ctx' are incompatible.
                    Type 'HandlerContext<Record<string, string>>' is missing the following properties from type 'Request': cache, credentials, destination, headers, and 17 more.
await start(routes);
            ~~~~~~
    at file:///C:/Users/sylva/Documents/Projects/OpenSource/test_fresh/main.ts:10:13
Watcher Process finished. Restarting on file change...

`fresh routes add <pattern>`

A subcommand to create a new route file at the given pattern. Automatically runs fresh manifest after creating the new route.

Write documentation

Following features require documentation:

• Architecture of a fresh app
• Islands
• _app.tsx
• _render.tsx
• _404.tsx
• _500.tsx
• _middleware.tsx
• Static files
• Custom handlers
• Using POST & forms
• <Head> component

`fresh manifest --watch`

What are your thoughts re: a new --watch option for fresh manifest?

If you think it’s worth exploration, do you suppose it’d be dependent or complementary to the stated issue? (i.e. Could they be worked on in parallel?)

(BTW, I really admire your’s and others’ work on this project—especially the JIT bundler. Truly liberating DX.)

Originally posted by @tylerbrostrom in #123 (comment)

Type check `www/` and `examples/counter/` in CI

Add pages/_app.tsx component support

This component would surround the page component. It can be used to do some setup for each page (for example inject context into the render tree). If no page is created, a default one is used. Example of a custom pages/_app.tsx:

import { h, AppProps } from "../deps.ts";
import { AuthProvider } from "../components/Auth.tsx";

export default function App({ Component }: AppProps) {
  return (
    <AuthProvider>
      <Component />
    </AuthProvider>
  );
}

`./routes/[id]/[path].tsx` catches request for `_frsh/refresh.js`

Should we move this block up?
https://github.com/lucacasonato/fresh/blob/026ed86f4009fc0a35463d43218bf8c34aead98e/src/server/context.ts#L395

Issue with fresh init project

https://github.com/lucacasonato/fresh/blob/main/src/cli/init.ts#L135

Needs to be ../../server_deps.ts :)
Really liking the new island concept by the way.

Serving Static Files

Hello,

Is it possible to serve static files with Fresh?

Thanks,
Quenio

Dev/Prod mode?

https://github.com/lucacasonato/fresh/blob/95289380f3f8bb85c8cc2d0fc3e5ab2ab4de9962/src/server/context.ts#L39

Dev/Prod mode is determined by assuming the end user is using Deno Deploy. I just set a random string for now in my use case but would be nice if this was a config option or something agnostic to the deployment environment. Or even just something to mention how to manually override in the docs.

Use Deno.readFile for loading JS and static files

Preload dependant chunks of entrypoint

To get the dependant chunks we can use the esbuild metafile: https://esbuild.github.io/api/#metafile.

Run lighthouse against preview deployments in CI

It should check that the page gets a 100/100/100/100 Lighthouse score, and that JS / CSS size stay below certain limits.

Trailing slash handling

We need to figure out how to deal with trailing slashes.

I think best would be to follow the Next.js example of redirecting paths with trailing slashes to their counterpart without a trailing slash.

Docs page is broken on site.

Problem

https://fresh.deno.dev/docs errors

This fresh.deno.dev page can’t be foundNo webpage was found for the web address: https://fresh.deno.dev/docs
HTTP ERROR 404

Documentation

Add documentation and example page. Domain needs bikeshedding. fresh.dev would be awesome, but very expensive.

Detect out of date manifest on startup

One of the major pitfalls of fresh is that the manifest needs to be updated after adding islands or routes by using fresh manifest. If you forget to do this, pages just don't show up. While it is not possible for us to automatically update the manifest at runtime, we can detect discrepancies between the disk and the manifest at startup and just error out until the user runs fresh manifest.

Let's do that.

Consider generating JS bundles all at once

That way we can codesplit between the bundles.

`fresh islands add <name>`

A subcommand to create a new island with the given name. Automatically runs fresh manifest after creating the new island.

Give users a way to opt out of client side rendering

export const config = {
  static: true
};

This would stop any client JS from being imported. Good for marketing pages.