npm package: @12degrees/website-builder-www
Description: website-builder plugin for fastify
Latest version: 0.11.0

# @12degrees/website-builder-www

A fastify plugin for the website-builder library

## Installation

Install with npm:

```bash
npm install @12degrees/website-builder-www
```

Install with pnpm:

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

## Usage

Add following options to your config

```typescript
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`:

```typescript
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.

```typescript
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](https://www.w3.org/TR/ltli/).

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

```typescript
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](https://www.npmjs.com/package/@fastify/static).

**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:

  ```html
  <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](https://www.npmjs.com/package/@fastify/view).

**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:

```nunjucks
<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:

  ```css
  /* 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:

  ```nunjucks
  <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:
  
  ```nunjucks
  <link rel="stylesheet" href="/static/style.css" media="screen, print" />
  <link rel="stylesheet" href="/static/css/styles.css" media="screen, print" />
  ```