Modules and Plugins 🔌

has an extensible module system, which is used internally to provide features such as frontmatter and meta information for pages.

Adding a Module

Use the modules option in iles.config.ts to add modules to your application.

// iles.config.ts
import { defineConfig } from 'iles'

import icons from '@islands/icons'

export default defineConfig({
  modules: [
    // Automatically imported and instantiated
    '@islands/headings',

    // Use an array to pass options
    ['@islands/prism', { showLineNumbers: true }] ,

    // Manually imported, provides better type-inference
    icons({ autoInstall: false }),

    // A one-off module that won't be published
    {
      name: 'custom-module',
      configResolved (config) {
        console.log({ config })
      },
    },
  ],
})

Authoring a Module

Modules in have access to the same configuration options as in iles.config.ts, and can make use of the config and configResolved hooks that work similarly to those in Vite.

You can start your own module package by running:

pnpm init iles-module@next # or npm or yarn

Module packages should be "type": "module" and have a default ESM export, which is used to instantiate the module when the user provides it as a string.

No Need for Packages

If you don't intend to publish it you can always import a local file or provide it inline instead.

Official Modules

@islands/headings

A module that injects a rehype plugin to parse headings in MDX documents:

• 🔗 adds an id to headings and injects an anchor tag to link them

• 🏷 automatically extracts the title from an <h1> and sets frontmatter.title

• 📖 sets meta.headings to enable rendering sidebars and table of contents

// iles.config.ts
import { defineConfig } from 'iles'

export default defineConfig({
  modules: [
    '@islands/headings',
  ],
})

@islands/icons

A module to add and configure unplugin-icons:

• ✨ autoInstall enabled by default, and icon prefix to prevent conflicts

• 🧱 configures the unplugin-vue-components resolver automatically

• 🎨 files in the /icons dir available as the app collection, <IconApp...

  modules: [
    '@islands/icons',
  ],

@islands/feed

A module to generate RSS and Atom feeds:

• 📻 supports RSS, Atom, and JSON formats

• ⚡️ HMR during development to debug the result

• 💪🏼 strongly typed, powered by [feed][feed]

  modules: [
    '@islands/feed',
  ],

Visit @islands/feed for usage instructions, or see this example.

@islands/prism

A module that injects a remark plugin to highlight code blocks in MDX documents:

• 💎 uses prismjs supporting a wide variety of programming languages

• 🔦 highlight specific lines ({3}, {7-13}, or {16,23-27,40})

• 🔢 display line numbers (showLineNumbers)

• 🚀 faster than @mapbox/rehype-prism, remark-prism and rehype-prism-plus

Check the readme for more information.

  modules: [
    '@islands/prism'
  ],

@islands/mdx

Shipped inside to provides MDX support, powered by xdm.

• 🧩 fully customizable with remark and rehype plugins
• 🧱 components are resolved automatically

  // Example config from "The Vue Point in îles"
  markdown: {
    rehypePlugins: [
      ['@mapbox/rehype-prism', { alias: { markup: ['html', 'vue'] } }],
    ],
  },

@islands/pages

Shipped inside to provide support for pages.

• 🛣 file-based routing
• 🎣 hooks to extend frontmatter and route data
• 📄 adds support for a <page> block in Vue single-file components

  extendFrontmatter (frontmatter, filename) {
    if (filename.includes('/posts/'))
      frontmatter.layout = 'post'
  },
  extendRoute (route) {
    if (route.path.startsWith('/posts'))
      route.path = path.replace(/[\d-]+/, '') // remove date
  },
  extendRoutes (routes) {
    routes.push({ path: '/custom', name: 'Custom', componentFilename: ... }))
  },

Customizing Frontmatter

extendFrontmatter is very flexible, you could use it to:

• Infer the title or date from the filename
• Set a different layout for all pages in a specific dir
• Provide additional data to use in the page, such as gitLastUpdated

Vite Plugins

You can use any Vite.js plugins by configuring them as usual, but note that the following plugins are already included and pre-configured for you.

The examples list some of the defaults for each plugin.

You can provide additional options for each of them using iles.config.ts.

@vitejs/plugin-vue

Provides Vue 3 Single File Components support.

// iles.config.ts
import { defineConfig } from 'iles'

export default defineConfig({
  vue: {
    refTransform: true,
  },
})

unplugin-vue-components

Enables auto-importing Vue components, and is leveraged internally to support automatic component resolution in MDX files.

  // Example config from "The Vue Point in îles"
  components: {
    resolvers: [iconsResolver({ componentPrefix: '' })],
  },

vite-plugin-solid

Provides support for SolidJS islands.

Auto-installed when configuring jsx: 'solid', solid: true, or providing plugin options for solid in iles.config.ts.

@preact/preset-vite

Provides support for Preact islands.

Auto-installed when configuring jsx: 'preact', preact: true, or providing plugin options for preact in iles.config.ts.

@sveltejs/vite-plugin-svelte

Provides support for Svelte islands.

Auto-installed when configuring svelte: true, or providing plugin options for svelte in iles.config.ts.