{"_id":"@arcmantle/vite-plugin-html-module","name":"@arcmantle/vite-plugin-html-module","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@arcmantle/vite-plugin-html-module","version":"1.0.0","description":"Vite plugin that enables importing HTML files as modules.","repository":{"type":"git","url":"git+https://github.com/arcmantle/vite-plugin-html-module.git"},"license":"Apache-2.0","author":{"name":"Kristoffer Roen-Lie"},"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","dependencies":{"@parse5/tools":"^0.5.0","parse5":"^7.2.1"},"devDependencies":{"@arcmantle/tsconfig":"^1.0.9","@types/node":"^24.0.14","rimraf":"^6.0.1","typescript":"^5.8.3","vite":"^7.0.0"},"engines":{"node":">=22"},"scripts":{"build":"rimraf dist && tsc --project ./src/tsconfig.json"},"_id":"@arcmantle/vite-plugin-html-module@1.0.0","bugs":{"url":"https://github.com/arcmantle/vite-plugin-html-module/issues"},"homepage":"https://github.com/arcmantle/vite-plugin-html-module#readme","_integrity":"sha512-LSeM2FWZB3mDsOYwD0QDTf7xy3NI4Vy9TncMhWT6fzaZyV+1C4G8LEkuZWooYAQAsYQ4/0XQDpSrulR8UFXtfQ==","_resolved":"/tmp/215e565e12b33a297f212441b40d8f10/arcmantle-vite-plugin-html-module-1.0.0.tgz","_from":"file:arcmantle-vite-plugin-html-module-1.0.0.tgz","_nodeVersion":"24.4.1","_npmVersion":"11.4.2","dist":{"integrity":"sha512-LSeM2FWZB3mDsOYwD0QDTf7xy3NI4Vy9TncMhWT6fzaZyV+1C4G8LEkuZWooYAQAsYQ4/0XQDpSrulR8UFXtfQ==","shasum":"9b65b6240cb1b9039bd3b23f5686ae315f1517b2","tarball":"https://registry.npmjs.org/@arcmantle/vite-plugin-html-module/-/vite-plugin-html-module-1.0.0.tgz","fileCount":9,"unpackedSize":16822,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD/yTF/m0Q1pHiAjt6KFlGz3mYeHGuVl+0RZyCM5rTdYgIhAJ2J8XZX/BK3NuPgOSGit28zZ+4h5NHbcY8Z3qc7zWs2"}]},"_npmUser":{"name":"roenlie","email":"kristofferroenlie@gmail.com"},"directories":{},"maintainers":[{"name":"roenlie","email":"kristofferroenlie@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/vite-plugin-html-module_1.0.0_1752793297297_0.6569992674593441"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-17T23:01:37.165Z","1.0.0":"2025-07-17T23:01:37.482Z","modified":"2025-07-17T23:01:37.794Z"},"maintainers":[{"name":"roenlie","email":"kristofferroenlie@gmail.com"}],"description":"Vite plugin that enables importing HTML files as modules.","homepage":"https://github.com/arcmantle/vite-plugin-html-module#readme","repository":{"type":"git","url":"git+https://github.com/arcmantle/vite-plugin-html-module.git"},"author":{"name":"Kristoffer Roen-Lie"},"bugs":{"url":"https://github.com/arcmantle/vite-plugin-html-module/issues"},"license":"Apache-2.0","readme":"# @arcmantle/vite-plugin-html-module\n\nA Vite plugin that enables importing HTML files as modules, supporting the [HTML Modules proposal](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/html-modules-explainer.md). Transform HTML files into JavaScript modules that export DOM nodes for use in your applications.\n\n## Features\n\n- 🏗️ **HTML Module Support**: Import HTML files directly as JavaScript modules\n- 🔍 **Element ID Export**: Optionally export elements with IDs as named exports\n- 📦 **TypeScript Support**: Includes TypeScript declarations for seamless integration\n- ⚡ **Vite Integration**: Built specifically for Vite with hot reload support\n- 🎯 **Standards-Based**: Follows the emerging HTML Modules web standard\n\n## Installation\n\n```bash\nnpm install @arcmantle/vite-plugin-html-module\n# or\npnpm add @arcmantle/vite-plugin-html-module\n# or\nyarn add @arcmantle/vite-plugin-html-module\n```\n\n## Usage\n\n### Basic Setup\n\nAdd the plugin to your `vite.config.ts`:\n\n```typescript\nimport { htmlModules } from '@arcmantle/vite-plugin-html-module';\nimport { defineConfig } from 'vite';\n\nexport default defineConfig({\n  plugins: [\n    htmlModules()\n  ]\n});\n```\n\n### TypeScript Configuration\n\nInclude the client types in your `tsconfig.json`:\n\n```json\n{\n  \"compilerOptions\": {\n    \"types\": [\"@arcmantle/vite-plugin-html-module/client\"]\n  }\n}\n```\n\n### Importing HTML Files\n\nImport HTML files using the `with { type: 'html' }` syntax:\n\n```typescript\nimport template from './template.html' with { type: 'html' };\n\n// The default export is a Document object\nconsole.log(template); // Document\n\n// Use the document as needed\ndocument.body.appendChild(template.body.firstElementChild);\n```\n\n### With Element ID Exports\n\nEnable element ID exports in your configuration:\n\n```typescript\nimport { htmlModules } from '@arcmantle/vite-plugin-html-module';\n\nexport default defineConfig({\n  plugins: [\n    htmlModules({ exportIds: true })\n  ]\n});\n```\n\nGiven an HTML file like this:\n\n```html\n<!-- template.html -->\n<div id=\"container\">\n  <h1 id=\"title\">Hello World</h1>\n  <button id=\"my-button\">Click me</button>\n</div>\n```\n\nYou can import both the document and individual elements:\n\n```typescript\nimport template, { container, title } from './template.html' with { type: 'html' };\n\n// Access the full document\nconsole.log(template); // Document\n\n// Access individual elements by their IDs\nconsole.log(container); // <div id=\"container\">...</div>\nconsole.log(title); // <h1 id=\"title\">Hello World</h1>\n\n// Elements with invalid JavaScript identifiers are exported with quotes\nimport template, { 'my-button': myButton } from './template.html' with { type: 'html' };\nconsole.log(myButton); // <button id=\"my-button\">Click me</button>\n```\n\n## Configuration Options\n\n### `exportIds`\n\n- **Type**: `boolean`\n- **Default**: `false`\n- **Description**: When enabled, elements with `id` attributes are exported as named exports. Elements with valid JavaScript identifiers are exported directly, while others are exported with quoted names.\n\n```typescript\nhtmlModules({\n  exportIds: true  // Enable ID-based exports\n})\n```\n\n## How It Works\n\n1. **Detection**: The plugin detects imports of `.html` files that use the `with { type: 'html' }` import assertion\n2. **Parsing**: HTML content is parsed using [parse5](https://github.com/inikulin/parse5) to extract element information\n3. **Transformation**: The HTML is transformed into a JavaScript module that:\n   - Creates a `DOMParser` instance\n   - Parses the HTML string into a `Document`\n   - Exports the document as the default export\n   - Optionally exports individual elements by their IDs\n4. **Type Safety**: TypeScript declarations ensure proper typing for imported HTML modules\n\n## Browser Compatibility\n\nThis plugin transforms HTML modules at build time, so the generated code runs in any environment that supports:\n\n- `DOMParser` API (all modern browsers)\n- ES modules\n\n## Requirements\n\n- Node.js >= 22\n- Vite >= 7.0.0\n\n## Dependencies\n\n- **parse5**: HTML parser for processing HTML files\n- **@parse5/tools**: Additional tools for HTML parsing and manipulation\n\n## License\n\nApache-2.0\n\n## Contributing\n\nThis package is part of the Arcmantle Weave monorepo. Contributions are welcome!\n\n---\n\n**Note**: This plugin implements support for the HTML Modules proposal, which is still evolving. The syntax and behavior may change as the specification develops.\n","readmeFilename":"README.md","_rev":"1-ad22cea5d201496d206a350f26cbd38b"}