# @brillout/html

Latest version **0.3.2** (published 2020-11-12) · 0 weekly downloads

## Install

```sh
npm install @brillout/html
pnpm add @brillout/html
yarn add @brillout/html
bun add @brillout/html
```

## Health

**Score 10/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; low quality score; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.2 |
| Published | 2020-11-12 |
| First published | 2019-06-24 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 24.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 6 |
| Maintainers | brillout |

## Links

- npm: https://www.npmjs.com/package/@brillout/html
- Repository: https://github.com/brillout/html
- Homepage: https://github.com/brillout/html#readme
- Issues: https://github.com/brillout/html/issues
- npm.io page: https://npm.io/package/@brillout/html

## Dependencies (2)

- [@brillout/reassert](https://npm.io/package/@brillout/reassert.md) ^0.1.1
- [@brillout/project-files](https://npm.io/package/@brillout/project-files.md) ^0.5.1

## Recent versions

- 0.3.2 (latest) — 2020-11-12
- 0.3.1 — 2019-07-02
- 0.3.0 — 2019-06-27
- 0.2.1 — 2019-06-25
- 0.2.0 — 2019-06-24

## README

<!---






    WARNING, READ THIS.
    This is a computed file. Do not edit.
    Edit `/readme.template.md` instead.












    WARNING, READ THIS.
    This is a computed file. Do not edit.
    Edit `/readme.template.md` instead.












    WARNING, READ THIS.
    This is a computed file. Do not edit.
    Edit `/readme.template.md` instead.












    WARNING, READ THIS.
    This is a computed file. Do not edit.
    Edit `/readme.template.md` instead.












    WARNING, READ THIS.
    This is a computed file. Do not edit.
    Edit `/readme.template.md` instead.






-->
# `@brillout/html`

Small vanilla JavaScript library to generate HTML documents.

It is typically used in combination with a modern view library that supports server side rendering such as React or Vue.

The main content of the HTML is generated by React/Vue and the rest of the HTML is generated by `@brillout/html`.

It used to generated the "outer part" and meta tags such as
`<!DOCTYPE html>`,
`<body>`,
`<head>`,
`<style>`,
`<script>`.

It is designed to be entirely flexible: you have full control over the generated HTML.

#### Contents

 - [Usage](#usage)
 - [API](#api)

<br/>
<br/>




### Usage

There are two ways to control the generated HTML:
 - By using the options of `html()`.
 - By creating an `index.html` file.

Example:

~~~js
// ./examples/basic/index.js

const html = require('@brillout/html'); // npm install @brillout/html

console.log(html({
    title: 'Example Page',
    description: 'Some Description.',
    favicon: '/static/logo.png',
    scripts: ['/static/bundle.js'],
    styles: ['/static/style.css'],
    head: ['<link rel="manifest" href="/manifest.webmanifest">'],
    body: ['<h1>Welcome</h1>'],
}));
~~~

Result:

~~~html
<!DOCTYPE html>
<html>
  <head>
  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
  <meta charset="utf-8">
    <title>Example Page</title>
    <link rel="shortcut icon" href="/static/logo.png">
    <meta name="description" content="Some Description.">
    <link href="/static/style.css" rel="stylesheet">
    <link rel="manifest" href="/manifest.webmanifest">
  </head>
  <body>
    <h1>Welcome</h1>
    <script src="/static/bundle.js" type="text/javascript"></script>
  </body>
</html>
~~~

The default base HTML document is:

~~~html
<!-- ./index.html -->

<!DOCTYPE html>
<html>
  <head>
  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
  <meta charset="utf-8">
    !HEAD
  </head>
  <body>
    !BODY
  </body>
</html>
~~~

But you can as well define a custom base HTML document.
Simply create a `index.html` file somewhere in your project's directory:

~~~html
<!-- ./examples/custom-base/index.html -->

<!DOCTYPE html>
<html>
    <head>
        <title>Title set over index.html file</title>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
        !HEAD
    </head>
    <body>
        !BODY
    </body>
</html>
~~~

~~~js
// ./examples/custom-base/index.js

const html = require('@brillout/html'); // npm install @brillout/html

// `@brillout/html` automatically finds your `index.html` file.

console.log(html({
    styles: ['/static/style.css'],
    scripts: ['/static/bundle.js'],
    body: ['<h1>Welcome</h1>'],
}));
~~~

Result:

~~~html
<!DOCTYPE html>
<html>
    <head>
        <title>Title set over index.html file</title>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
        <link href="/static/style.css" rel="stylesheet">
    </head>
    <body>
        <h1>Welcome</h1>
        <script src="/static/bundle.js" type="text/javascript"></script>
    </body>
</html>
~~~

Also note that you can use the `html` option instead of creating a file.
See the next section "API" for an example.

<br/>
<br/>




### API

The following example exhibits all options:

~~~js
// ./examples/full/index.js

const html = require('@brillout/html'); // npm install @brillout/html

console.log(html({
    description: 'Some Description.',
    favicon: '/static/some-logo.png',
    scripts: [
        '/static/bundle.js',
        {
            src: 'https://example.org/neat-script.js',
            async: true,
            type: 'application/javascript',
        },
        {
            src: '/static/es6-module.mjs',
            defer: true,
            'data-some-custom-attribute': 'with some custom value',
            type: 'module'
        },
        {
            sourceCode: "console.log('hello from `@brillout/html`')",
        },
    ],
    styles: [
        '/static/style.css',
    ],
    inlineStyles: [
        'body { margin: 0 }'
    ],
    charset: 'utf-8',
    viewport: 'width=device-width',
    body: ['<div>Hello World</div>'],
    head: ['<custom-element attr-1 attr-2="1337"/>'],
    html: (
`<html>
    <head>
        <title>Title set over the \`html\` option</title>
        !HEAD
    </head>
    <body>
        !BODY
    </body>
</html>
`
    ),
}));
~~~

Result:

~~~html
<html>
    <head>
        <title>Title set over the `html` option</title>
        <link ref="icon" href="/static/some-logo.png" />
        <meta name="description" content="Some Description.">
        <meta name="viewport" content="width=device-width">
        <meta charset="utf-8">
        <link href="/static/style.css" rel="stylesheet">
        <style>body { margin: 0 }</style>
        <custom-element attr-1 attr-2="1337"/>
    </head>
    <body>
        <div>Hello World</div>
        <script src="/static/bundle.js" type="text/javascript"></script>
        <script src="https://example.org/neat-script.js" async type="application/javascript"></script>
        <script src="/static/es6-module.mjs" defer data-some-custom-attribute="with some custom value" type="module"></script>
        <script type="text/javascript">console.log('hello from `@brillout/html`')</script>
    </body>
</html>
~~~

<br/>
<br/>



<!---






    WARNING, READ THIS.
    This is a computed file. Do not edit.
    Edit `/readme.template.md` instead.












    WARNING, READ THIS.
    This is a computed file. Do not edit.
    Edit `/readme.template.md` instead.












    WARNING, READ THIS.
    This is a computed file. Do not edit.
    Edit `/readme.template.md` instead.












    WARNING, READ THIS.
    This is a computed file. Do not edit.
    Edit `/readme.template.md` instead.












    WARNING, READ THIS.
    This is a computed file. Do not edit.
    Edit `/readme.template.md` instead.






-->

---
_Source: https://npm.io/package/@brillout/html · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
