@curi/static

v2.0.2

About

The @curi/static package is for creating static assets for your server. Its exported functions should be used in a build script, not the source of an application.

Installation

npm install @curi/static

staticFiles

The staticFiles function is used to generate HTML files for a static website and save them to the disk. An HTML file will be created for each page that you provide.

Files will be created as index.html in the directory for their path. For example, the page for the pathname /about would create an /about/index.html file.

import { staticFiles } from '@curi/static';
import { join } from "path";

import routes from "../src/routes";

staticFiles({
  routes,
  pages: [{ name: "Home" }, { name: "About" }],
  output: {
    dir: join(process.cwd(), "public"),
    render: () => {...}
  }
});

staticFiles returns a Promise that resolve with an array of results. Each entry in the results array contains the pathname of the result, a success boolean, and, if success is false, the error that occurred.

It can be useful to log the results to easily see what pages were successfully built and which had issues.

staticFiles({...})
  .then(results => {
    let resultString = results
      .map(result => {
        return result.success
          ? `✔ ${result.pathname}`
          : `✖ ${result.pathname} (${result.error.message})`;
      })
      .join("\n");
    console.log(resultString);
  });

Arguments

The staticFiles functions is passed an object of arguments.

pages

An array of page descriptors. A page descriptor is an object with a name property defining which route to generate a page for. If the route (or any of its ancestors) has any params, they should be passed as an object with the params property.

let pages = [
  { name: "Home" },
  { name: "User", params: { id: 1 }},
  { name: "User", params: { id: 2 }},
];


staticFiles({
  // ...
  pages
});

router

The router property is an object with two properties: routes and options.

routes

routes is an array of route descriptors. This is the same array that you would use to create a router in client-side code.

let routes = prepare_routes([
  {
    name: "Home",
    path: "",
  },
  {
    name: "User",
    path: "u/:id"
  }
]);

staticFiles({
  // ...
  router: {
    routes
  }
});

options

The options object is the options for a router. This is only necessary if you need to use side effects or other route options.

When you call staticFiles, a router is created for each page. staticFiles creates its own history instances, and gets its routes from the routes options, but the router may also need to be provided with other options.

staticFiles({
  // ...
  router: {
    options: {
      sideEffects: [...]
    }
  }
});

fallback

Some hosts allow you to provide a fallback page for when a request doesn't match any of your generated HTML files. The fallback option takes the pathname it should generate page contents for and the filename to save the file as.

staticFiles({
  // ...
  fallback: {
    pathname: "/404",
    filename: "404.html"
  }
});

output

The output property is used to describe how output files are generated and where they are stored.

render

A function that takes the emitted response, navigation, and router for a location and returns the page's HTML.

How the content is generated will depend on what type of application is being built. For a React application, this would call the renderToString method from react-dom/server. A Vue application would use vue-server-renderer.

render is expected to return the complete HTML for a page

If the response should not be rendered, the render function should throw an error.

// for a React application
import { renderToString } from "react-dom";
import { createRouterComponent } from "@curi/react-dom";

function render(emitted) {
  let { router, response } = emitted;
  // if the route shouldn't be rendered, throw
  if (response.redirect) {
    throw new Error(`${response.location.pathname} redirects`);
  }

  let Router = createRouterComponent(router);
  // generate markup
  let markup = renderToString(
    <Router>
      <App />
    </Router>
  );

  // return full HTML for the page
  return `<!doctype html>
<html>
  <head>...</head>
  <body>
    <div id="root">
      ${markup}
    </div>
  </body>
</html>`;
}

staticFiles({
  // ...
  output: {
    render
  }
});

dir

The folder where the generated HTML files should be saved.

staticFiles({
  // ...
  output: {
    dir: "dist"
  }
})

routes = prepare_routes([
  {
    name: "Home",
    path: "",
  },
  {
    name: "User",
    path: "u/:id"
  }
]);


let paths = pathnames({
  // ...
  routes
});

pages

let pages = [
  { name: "Home" },
  { name: "User", params: { id: 1 }},
  { name: "User", params: { id: 2 }},
];


let paths = pathnames({
  // ...
  pages
});

routerOptions

The options for a router, predominantly useful for passing any route interactions the application may need while rendering.

import active from "@curi/active";
let routerOptions = {
  routes: [active()]
};

let paths = pathnames({
  // ...
  routerOptions
});