# vite-plugin-unified

> ![GitHub package.json version](https://img.shields.io/github/package-json/v/steve-py96/vite-plugin-unified?style=flat-square&color=000000)

Latest version **0.1.1** (published 2022-08-13) · UNLICENSED license · 0 weekly downloads

## Install

```sh
npm install vite-plugin-unified
pnpm add vite-plugin-unified
yarn add vite-plugin-unified
bun add vite-plugin-unified
```

## Health

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

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2022-08-13 |
| First published | 2022-08-11 |
| Weekly downloads | 0 |
| License | UNLICENSED |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 71.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | steve_py96 |
| Keywords | vite, plugin, unified |

## Links

- npm: https://www.npmjs.com/package/vite-plugin-unified
- Repository: https://github.com/steve-py96/vite-plugin-unified
- Homepage: https://github.com/steve-py96/vite-plugin-unified#readme
- Issues: https://github.com/steve-py96/vite-plugin-unified/issues
- npm.io page: https://npm.io/package/vite-plugin-unified

## Dependencies (4)

- [jiti](https://npm.io/package/jiti.md) ^1.14.0
- [fast-glob](https://npm.io/package/fast-glob.md) ^3.2.11
- [hastscript](https://npm.io/package/hastscript.md) ^7.0.2
- [@types/unist](https://npm.io/package/@types/unist.md) ^2.0.6

## Alternatives

- [raw-loader](https://npm.io/package/raw-loader.md) — 4.3M weekly downloads
- [plop](https://npm.io/package/plop.md) — 1.4M weekly downloads
- [webpack-deadcode-plugin](https://npm.io/package/webpack-deadcode-plugin.md) — 80.3K weekly downloads
- [@storybook/preact-vite](https://npm.io/package/@storybook/preact-vite.md) — 54.2K weekly downloads
- [vite-plugin-transform](https://npm.io/package/vite-plugin-transform.md) — 2.4K weekly downloads

## Recent versions

- 0.1.1 (latest) — 2022-08-13
- 0.1.0 — 2022-08-13
- 0.0.9 — 2022-08-13
- 0.0.8 — 2022-08-13
- 0.0.7 — 2022-08-13
- 0.0.6 — 2022-08-12
- 0.0.5 — 2022-08-11
- 0.0.4 — 2022-08-11
- 0.0.3 — 2022-08-11
- 0.0.2 — 2022-08-11
- 0.0.1 — 2022-08-11

## README

![GitHub package.json version](https://img.shields.io/github/package-json/v/steve-py96/vite-plugin-unified?style=flat-square&color=000000)

# vite-plugin-unified

Just a little [vite](https://github.com/vitejs/vite) plugin that works with [unified](https://github.com/unifiedjs/unified).

## playground

[Stackblitz example](https://stackblitz.com/edit/vite-plugin-unified)

## how to use

1. `npm install -D vite-plugin-unified` / `yarn add -D vite-plugin-unified` / `pnpm add -D vite-plugin-unified`
2. include it in your vite plugins

```typescript
// inside your vite.config.ts f.e.

export default defineConfig({
  plugins: [
    vitePluginUnified({
      // your config
    }),
  ],
});
```

For hot-reloading on your processed pages (if your output is HTML) you can include `rehypeVite` into your unified chain.
It injects the vite client in development mode automatically and provides further configurations (see section [rehypeVite](#rehypeVite)).
For context-based processings (like a dev setup which differs slightly from the prod build) you have also the vite-context within the `vite-plugin-unified` context.

## configuration vite-plugin-unified

(just taken out of [src/types.ts](./src/types.ts)).

```typescript
type Config = Partial<{
  /** the directory for unified files (by default '/src/pages') */
  directory: string;

  /** the extensions to determinate what files to process (by default ['md']) */
  extensions: Array<string>;

  /** server settings */
  server: Partial<{
    /** enables caching on the dev server (by default true) */
    cache?: boolean;

    /** attach custom headers to the responses of your processed files */
    responseHeaders: OutgoingHttpHeaders;
  }>;

  /** build settings */
  build: Partial<{
    /** a glob to determinate all files to build (by default ./[directory]\/\*\*\/*.{[extensions]}) */
    glob?: string | Array<string>;

    /** the directory within dist where the builds will land (by default 'unified') */
    outDir?: string;

    /** the output format of the processing (by default 'html') */
    outFormat?: string | ((file: string) => string);
  }>;

  /** processing / transforming settings */
  transform: Partial<{
    /** the default transformer for all files without custom .unified.{js,ts} file (by default (content) => content) */
    defaultTransformer: Transform;

    /** the required export function of your custom .unified.{js,ts} files (by default 'transform') */
    exportName: string;
  }>;
}>;
```

## examples

### Markdown to HTML

```typescript
// within the vite plugins
vitePluginUnified({
  directory: '/src/pages',
  transform: {
    async defaultTransformer(content, context) {
      return await unified()
        .use(remarkParse)
        .use(remarkRehype)
        .use(context.plugins.rehypeVite, {
          scripts: '/src/markdownEntry.ts',
        })
        .use(rehypeFormat)
        .use(rehypeStringify)
        .process(content);
    },
  },
});
```

## rehypeVite

`vite-plugin-unified` provides every transformer (custom or defaultTransformer) a context which contains the `rehypeVite`-Plugin for unified.
`rehypeVite` allows you to create the document or add scripts, styles and attributes (to html, head and body only) to an existing document.
You can additionally control when those scripts / styles should be included (like dev-only, prod-only) since the plugin is aware of the vite-context aswell.

### configuration rehypeVite

(just taken out of [src/types.ts](./src/plugins/types.ts)).

```typescript
export type { Options, Element, HChild };

type h = typeof import('hastscript').h;

type Element = ReturnType<h>;
type HChild = Parameters<h>[2];

type WithGeneral<T> = T &
  Partial<{
    _target: 'head' | 'body';
    _ignore: boolean;
    attributes?: Record<string, string>;
  }>;
type Script = WithGeneral<{ src: string }>;
type Style = WithGeneral<{ href: string }>;
type Inline = WithGeneral<{
  content: string;
}>;

type Options = Partial<{
  /** add attributes to html, head and/or body (f.e. lang on html) */
  attributes?: Partial<{
    /** add attributes on \<html\> */
    html: Record<string, string>;

    /** add attributes on \<head\> */
    head: Record<string, string>;

    /** add attributes on \<body\> */
    body: Record<string, string>;
  }>;

  /** add custom stuff to head (with hastscript), note: this only is used when there's no document existing yet! default here is the vscode emmet html head without title */
  customHead?: (hastscript: h) => HChild | Array<HChild>;

  /** add a custom title to the page, note: this only is used when there's no document existing yet and no customHead is used! default here is 'unified' */
  title?: string;

  /** add custom stuff to body (with hastscript), note: this only is used when there's no document existing yet! */
  customBody?: (hastscript: h) => HChild | Array<HChild>;

  /** a custom container around all elements within the body, note: customBody content also goes into this container! */
  container?: (hastscript: h) => Element;

  /** add an inline script (by default in head, if provided as object modifiable) */
  inlineScript: string | Inline;

  /** a script source / an array of script sources (by default async in head, if provided as object modifiable) */
  scripts: string | Script | Array<string | Script>;

  /** add an inline style (by default in head, if provided as object modifiable) */
  inlineStyle: string | Inline;

  /** a stylesheet href / an array of stylesheets hrefs (by default in head, if provided as object modifiable) */
  styles: string | Style | Array<string | Style>;
}>;
```

## caching in dev

Since transforming a file will most probably always result in the same document there's an in-memory cache within the dev-server by default.
You can avoid it's from working by disabling it with `server.cache = false` (see [configuration](#configuration-vite-plugin-unified)), by adding `vite-plugin-unified-nocache` to the URL-Query (f.e. `?vite-plugin-unified-nocache`) or by sending the request with `cache-control: no-cache` header (which should be browser default if you hard-reload a page).

## upcoming

- more tests with vitest (each plugin yet missing)
- more configurations?

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