îles

Modules and Plugins 🔌

îles 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.

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 })
      },
    },
  ],
})

iles.config.ts

When providing a string, îles will automatically add the specified module to the development dependencies. Otherwise, add the package manually and run install.

Authoring a Module

Modules in îles 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 create 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 îles

@islands/excerpt

A module to extract an excerpt from MDX documents:

  • 📖 sets meta.excerpt, useful for SEO tags and RSS feeds

  • 🏷 can render HTML by using the excerpt prop in an MDX component

  • ⚙️ maxLength, separator, and extract options to customize excerpt

import { defineConfig } from 'iles'

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

iles.config.ts

Use meta to access a plain-text version of the excerpt for the current page:

const { meta } = usePage()
const text = meta.excerpt

When importing MDX components, you use the excerpt prop to render HTML:

<script setup>
import Introduction from '~/pages/intro.mdx'

const pages = useDocuments('~/pages/posts')
</script>

<template>
  <Introduction excerpt/>
  <template v-for="page in pages">
    <component :is="page" excerpt/>
  </template>
</template>

@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

import { defineConfig } from 'iles'

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

iles.config.ts

@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/images

A module that configures vite-plugin-image-presets, allowing you to easily define presets to optimize and convert images:

  • 🖼 define presets once, apply everywhere

  • 🔗 use presets directly in img, source, and in markdown!

  • 🖥 customize formats, srcset, & sizes

  • ⚡️ on-demand in dev, cached at build time 📦

Check the readme for more information, or see it in action.

@islands/feed

A module to generate RSS and Atom feeds, powered by feed:

  • 📻 supports RSS, Atom, and JSON formats

  • 💪🏼 strongly typed

  • ⚡️ HMR during development to debug the result

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

@islands/prism

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

Check the readme for more information.

  modules: [
    '@islands/prism'
  ],

@islands/pwa

A module to add and configure vite-plugin-pwa to make your website work offline, created by @userquin.

import { defineConfig } from 'iles'
import pwa from '@islands/pwa'

export default defineConfig({
  modules: [
    pwa(options),
  ],
})

iles.config.ts

See the PWA guide for more information.

@islands/mdx

Shipped inside îles to provide MDX support.

  markdown: {
    remarkPlugins: [
      'remark-gemoji',
    ],
  },

@islands/pages

Shipped inside îles 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 support for Single File Components with Vue 3.

import { defineConfig } from 'iles'

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

iles.config.ts

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.

Last Updated:

RSS Feeds
PWA