Skip to main content

Mike Allanson

Intro to Toast

toast is “an ES Modules based Jamstack framework”. See toast.dev for more info.

Getting started

Run npx create-toast minimal to create a barebones Toast site. Or npx create-toast to create a default starter that has Tailwind and MDX configured.

You can view the official starters in this repo.

Add a static page

By default Toast will check the /src/pages/ directory, turning each .js file into an html page at build time. Your .js file should export a Preact component.

The minimal starter gives you a /src/pages/index.js file, which builds to /public/index.html.

Provide data to pages

The /src/pages/ directory is great for static pages. What about adding external data to your pages?

You can use a toast.js file in the root of your project to hook into Toast’s page creation process.

A minimal toast.js file can look like this:

export const sourceData = async ({ setDataForSlug }) => {
  const componentSrc = `
import { h } from "preact";
export default props => <div>
  <h1>Hello, world</h1>
</div>
`;

  const pageArgs = {
    component: {
      mode: "source",
      value: componentSrc,
    },
  };

  await setDataForSlug("/my-page", pageArgs);

  return;
};

The key parts here are:

  • exporting a sourceData function
  • calling the setDataForSlug function

When Toast builds your site, it checks to see if your toast.js file exports a sourceData function. If yes, Toast will run your sourceData(), passing in Toast’s setDataForSlug function. You can check the Toast source to see how this is done.

You’re free to source your data however you like. When your data is ready, use setDataForSlug to provide the data for each slug (aka page).

setDataForSlug

setDataForSlug is used to create pages and provide them with data.

setDataForSlug requires slug and pageArgs parameters. slug sets the URL path for your created page. pageArgs defines how to render the page.

pageArgs is an object with two top level keys:

{
  component: {},
  data: {}
}
  • component describes the component that will be used to render the page
  • data provides any data that’s needed to render the page

Note: pageArgs can have other keys, you can read more about pageArgs in the Toast repo.

Calling setDataForSlug multiple times for the same slug will cause Toast to merge the pageArgs from every call.

Toast uses the same setDataForSlug API when creating pages from files in your /src/pages/ directory.

The above two points mean that you can push data into your filesystem components. For example:

// /src/pages/index.js
import { h } from "preact";

export default (props) => {
  return (
    <div>
      <h1>The Smallest Toast Example</h1>
      <p>This page built at {props.buildTime}</p>
    </div>
  );
};

// toast.js
export const sourceData = async ({ setDataForSlug }) => {
  await setDataForSlug("/", {
    data: {
      buildTime: new Date(),
    },
  });
};

This will create a page at /my-page that displays the time that the page was built.

Here’s the same example, except passing the component in to setDataForSlug:

export const sourceData = async ({ setDataForSlug }) => {
  const componentSrc = `
import { h } from "preact";
export default props => <div>
  <h1>Hello, world. {props.builtAt}</h1>
</div>
`;

  const pageArgs = {
    component: {
      mode: "source",
      value: componentSrc,
    },
    data: {
      builtAt: new Date(),
    },
  };

  await setDataForSlug("/my-page", pageArgs);

  return;
};

Wrap pages

Create a component at /src/page-wrapper.js and Toast will use it to wrap all of your pages. The default starter uses the page wrapper to:

import { h } from "preact";
import { Helmet } from "react-helmet";
import { MDXProvider } from "@mdx-js/preact";

const components = {
  codeblock: (props) => <div class="bg-gray-900" {...props} />,
};

export default function PageWrapper(props) {
  return (
    <MDXProvider components={components}>
      <div>
        <Helmet>
          <link rel="stylesheet" href="/styles.css" />
        </Helmet>
        {props.children}
      </div>
    </MDXProvider>
  );
}

The page content is available in props.children.

Remember pageArgs from before? You can use pageArgs to set a page wrapper programmatically.

In your sourceData function:

// toast.js
await setDataForSlug("/", {
  wrapper: {
    mode: "source",
    value: `
import { h } from "preact";
export default props => (
  <div style={{backgroundColor: 'hotpink';}}>
    {props.children}
  </div>
)
`,
  },
});

Programmatically setting the wrapper component is not implemented yet (using toast@0.3.43).

Static assets

The contents of /static will be copied into the root of the output directory (/public).

The file /static/fonts/my-font-file.woff2 will be available at the URL /fonts/my-font-file.woff2 in your built site.

Toast sites