@12degrees/website-builder-www

A fastify plugin for the website-builder library

Installation

Install with npm:

npm install @12degrees/website-builder-www

Install with pnpm:

pnpm add --filter "@scope/project" @12degrees/website-builder-www

Usage

Add following options to your config

import type { ApiConfig } from "@dzangolab/fastify-config";

const config: ApiConfig = {
  ...
    content: {
      tables: {
        content: process.env.CONTENT_TABLE as string
      },
      version: process.env.CONTENT_VERSION as string
    },
    i18n: {
      defaultLocale: process.env.DEFAULT_LOCALE as string,
      locales: ((process.env.LOCALES as string) || "en")
                .split(","),
    },
    static: {
      root: "src/public",
      // other fastifyViewoptions properties
    },
    view: {
      templates: "src/templates",
      // other fastifyStaticOptions properties
    },
  ...
};

export default config;

Register the plugin with your fastify instance in src/index.ts:

import wwwPlugin from "@12degrees/website-builder-fastify";
import Fastify from "fastify";

const start = async () => {
  const fastify = await Fastify();

  // Register website-builder-fastify plugin
  await fastify.register(wwwPlugin);

  try {
    await fastify.listen({
      port: 3000,
      host: "0.0.0.0",
    });
  } catch (error) {
    fastify.log.error(error);
  }
};

start();

Configuration

content

The content block is used to configure your application's content tables and versioning.

• tables: (optional) An object containing the table names for storing content.
  • content: The name of the table used to store content data.
• version: The current version of your application's content, useful for handling content updates.

content: {
  tables: {
    content: "content_table", // Name of the table for storing content
  },
  version: "1.0.0", // Current version of your content
}

i18n

The i18n block is used to configure localization settings for your application.

• defaultLocale (string): The default locale for your application. This locale must be included in the locales array.
• locales (array): Array of locales to support. Each locale is identified by a language tag as per the W3C Language Tag and Locale Identifiers.

Note: If the defaultLocale is not present in the locales array, the package will throw an error to ensure consistency.

i18n: {
  defaultLocale: "en", // Default locale for the application
  locales: ["en", "fr"], // Supported locales
}

static (optional)

All the additional plugin options provided by the Fastify static package except for prefix are available here. For more details, refer to the @fastify/static documentation.

Default path for static files:

The default path for serving static assets is src/public. You can change this by setting the root property in static.

Static file prefix requirement:

All static files must follow the /static/ prefix, which is enforced by the package and cannot be overridden.

If you have a CSS file or an image in the src/public folder, they will be served under the /static/ prefix.

For example:

• A CSS file located at src/public/css/style.css will be available at:

  <link rel="stylesheet" href="/static/css/style.css">

view (optional)

All the additional plugin options provided by the Fastify view package except for engine and root configuration are available here. For more details, refer to @fastify/view documentation.

Default path for templates:

By default, templates are rendered from the src/views directory. You can customize this path by setting the templates property in view.

Template setup

The @12degrees/website-builder-fastify package comes with a basic template to help you get started quickly. This template includes a simple structure that you can customize to fit your application's needs.

Using the basic template

While the package provides a basic template, it's essential to customize this template according to your application's specific requirements. This includes ensuring that the template contains all necessary links for CSS, JavaScript, and favicon files. These resources are critical for the proper styling and functionality of your web pages.

To achieve this, you will need to override the provided template file in your application. This allows you to add and modify elements such as stylesheets, scripts, and other assets that are unique to your project.

Stylesheets setup

The @12degrees/website-builder-www package includes a stylesheets.njk template that handles the inclusion of default stylesheets. You can include this template or override it based on your project's needs.

Default stylesheets provided by the package

The stylesheets.njk template provided by the package looks like this:

<link rel="stylesheet" href="/static/style.css" media="screen, print"/>

Customizing stylesheets

• Combining default and custom stylesheets: If you want to customize or extend the default styles, you can override the stylesheets.njk file in your project. Create your own styles.css file and import any custom CSS files. For example, if you have different component-specific styles, you can import them inside your custom styles.css. While doing this you can also import individual css from the package like this:

  /* custom stylesheets */
  @import "./header.css";
  @import "./footer.css";
  
  /* package stylesheets */
  @import "/static/css/benefits.css";
  @import "/static/css/hero.css";

  In this case your custom stylesheets.njk file looks like this:

  <link rel="stylesheet" href="/static/css/styles.css" media="screen, print" />

  Note: If you don't want to include individual component CSS from the package, you can simply import all the default styles at once, along with your custom styles.

  To do this, modify the stylesheets.njk file to include both the default package stylesheet and your custom stylesheet:

  <link rel="stylesheet" href="/static/style.css" media="screen, print" />
  <link rel="stylesheet" href="/static/css/styles.css" media="screen, print" />