astro-single-file

This Astro integration allows developers to bundle the CSS and HTML in a single file.

• Why
• Installation
• Usage
• Configuration
• Troubleshooting
• Contributing
• Acknowledgment

Why?

Recently, I had to build some HTML emails templates to send to some users where the final bundle is preferable to be in a single file for backend developers. That's why, only CSS and no JS files are being merged in the HTML file. If you would like to support JS files, you are welcome to submit a PR!

Installation

Automatic installation

Run the following command to install and set it up for you automatically

astro add astro-single-file # Follow the instructions

Manual installation

The astro add command-line tool automates the installation for you. Run one of the following commands in a new terminal window. (If you aren't sure which package manager you're using, run the first command.) Then, follow the prompts, and type "y" in the terminal (meaning "yes") for each one.

# Using NPM
npx astro add -D astro-single-file
# Using Yarn
yarn astro add -D astro-single-file
# Using PNPM
pnpx astro add -D astro-single-file

astro.config.mjs

import astroSingleFile from 'astro-single-file'

export default {
  // ...
  integrations: [astroSingleFile()],
}

Then, restart the dev server.

Usage

This integration will after the build process finishes, using astro:build:done hook. It will look in the build directory and it will find all the references in your HTML files where it references an external CSS file which it will replace. Then, it will remove those CSS files.

Configuration

Basic Usage

import astroSingleFile from 'astro-single-file'

export default {
  integrations: [astroSingleFile()]
}

Configuration Options

interface SingleFileConfig {
  /** Enable HTML/CSS minification (default: true) */
  minify?: boolean

  /** Lightning CSS transform options */
  lightningcss?: {
    /** Target browsers for autoprefixing */
    targets?: { [key: string]: number }
    /** Enable CSS drafts (nesting, etc) */
    drafts?: { nesting?: boolean }
    /** Additional Lightning CSS options */
    [key: string]: any
  }
}

Examples

Disable minification:

astroSingleFile({ minify: false })

Configure browser targets:

astroSingleFile({
  lightningcss: {
    targets: {
      safari: 13 << 16, // Safari 13+
      chrome: 95 << 16 // Chrome 95+
    }
  }
})

Enable CSS nesting:

astroSingleFile({
  lightningcss: {
    drafts: { nesting: true }
  }
})

Troubleshooting

• If your installation doesn't seem to be working, make sure to restart the dev server.
• If you edit and save a file and don't see your site update accordingly, try refreshing the page.
• If you edit and save a file and don't see your site update accordingly, try refreshing the page.
• If refreshing the page doesn't update your preview, or if a new installation doesn't seem to be working, then restart the dev server.

For help, check out the #support-threads channel on Discord. Our friendly Support Squad members are here to help!

You can also check our Astro Integration Documentation for more on integrations.

Contributing

This package is maintained by @onmax. You're welcome to submit an issue or PR!

Acknowledgment

Inspired by vite-plugin-singlefile.