{"id":24582722,"url":"https://github.com/octamap/mesa","last_synced_at":"2025-04-24T06:22:38.825Z","repository":{"id":271308259,"uuid":"913004582","full_name":"octamap/mesa","owner":"octamap","description":"Build-time HTML component engine","archived":false,"fork":false,"pushed_at":"2025-03-29T13:18:35.000Z","size":359,"stargazers_count":28,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-29T14:25:34.156Z","etag":null,"topics":["compiler","html","npm","vite"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@octamap/mesa ","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/octamap.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-06T20:50:00.000Z","updated_at":"2025-03-29T13:18:38.000Z","dependencies_parsed_at":"2025-01-06T23:31:54.767Z","dependency_job_id":"581a9ca2-6f07-44c9-b593-a59aa5a1ba81","html_url":"https://github.com/octamap/mesa","commit_stats":null,"previous_names":["octamap/mesa"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octamap%2Fmesa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octamap%2Fmesa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octamap%2Fmesa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octamap%2Fmesa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/octamap","download_url":"https://codeload.github.com/octamap/mesa/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250574666,"owners_count":21452597,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compiler","html","npm","vite"],"created_at":"2025-01-24T03:56:41.146Z","updated_at":"2025-04-24T06:22:38.806Z","avatar_url":"https://github.com/octamap.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 **Mesa – Build-Time HTML Components**  \n**@octamap/mesa**  \n\n## Status update - March 29, 2025 \nLots of improvements and changes are coming soon!! We are working on integrating a quite large feature. The goal is to release version 2.0.0 beta on April 30\n\n---\n\nMesa is a **build-time HTML component engine** that allows you to write reusable, declarative HTML components with scoped CSS and dynamic attributes — **without requiring runtime JavaScript to render them**.  \n\nWhether you're building a **static website**, a **micro-frontend architecture**, or **HTML-first** website development, Mesa keeps your pages **lightweight, SEO-friendly, and blazing fast**.  \n\n## 🛠️ **What is Mesa?**\n\nMesa allows you to:  \n\n1. **Write reusable HTML components**.  \n2. **Use them in other HTML files**.  \n3. **Automatically handle props, dynamic attributes, and scoped styles at build time**.\n\n## ⚡ Super quick reactivity\nNo need for large runtimes for reactivity (such as Vue, React \u0026 Svelte)\n\nMesa is framework agnostic. Achive the same level of reactivity by pairing it up with somthing quick and lightweight like alpine.js or HTMX for **⚡️super quick hydration⚡️**\n\n\n## 🎉 VS Code Extension!! (Beta)\nType completions \u0026 syntax highlighting is now supported through a brand new Mesa Visual Studio Code extension!! \n\n#### **Early Beta**:\n[Install Mesa VS Code Extension](https://marketplace.visualstudio.com/items?itemName=octamap.mesa)\n\n#### **Report issues**:\nThis extension is really new. Please send any issues with the extension to `extension@octamap.com`. \n\n## 🤯 Javascript with no runtime Javascript (NOT AVAILABLE YET, COMING SOON)\nMesa not only lets you create components without requiring runtime Javascript. Mesa also lets you **write Javascript without requiring runtime Javascript** 🤯. (new in since version 1.2.0). Read more about this [here](#-compile-time-javascript).\n\nThis feature will be expanded in the future (Make requests through tickets on github)\n\n## 📄 **1. Create a Component**\n\nDefine a reusable component in its own file:  \n\n### 📂 **my-custom-button.html**\n```html\n\u003cbutton class=\"close-button\"\u003e\n    \u003csvg\u003e...\u003c/svg\u003e\n\u003c/button\u003e\n\n\u003cstyle\u003e\n.close-button {\n    background: red;\n    color: white;\n    border: none;\n    padding: 8px 12px;\n    cursor: pointer;\n}\n\u003c/style\u003e\n```\n\n- The `\u003cbutton\u003e` contains your markup.  \n- The `\u003cstyle\u003e` block includes the scoped CSS.  \n\n---\n\n## 📄 **2. Use the Component in Another File**\n\nIn your main HTML file, simply use the `\u003cmy-custom-button\u003e` tag:  \n\n### 📂 **index.html**\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n    \u003clink rel=\"stylesheet\" href=\"component-styles.css\"\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003ch1\u003eWelcome to Mesa\u003c/h1\u003e\n    \u003cmy-custom-button @click=\"exampleEvent\"\u003e\u003c/my-custom-button\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n---\n\n## 🪄 **3. Mesa Works Its Magic at Build Time**\n\nMesa compiles the above into:\n\n### 📂 **index.html**\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n    \u003clink rel=\"stylesheet\" href=\"component-styles.css\"\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003ch1\u003eWelcome to Mesa\u003c/h1\u003e\n    \u003cbutton class=\"close-button\" @click=\"exampleEvent\"\u003e\n        \u003csvg\u003e...\u003c/svg\u003e\n    \u003c/button\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n### 📂 **component-styles.css**\n```css\n.close-button {\n    background: red;\n    color: white;\n    border: none;\n    padding: 8px 12px;\n    cursor: pointer;\n}\n```\n\n✅ **Props and attributes are passed automatically.**  \n✅ **Styles are extracted and scoped correctly.**  \n✅ **No runtime rendering — everything happens at build time.**  \n\n\n# ⚙️ **Features**\n\n### 📦 **1. Static Components, Dynamic Props**\nPass attributes and dynamic bindings directly on the root element:\n\n**index.html**\n```html\n\u003cmy-custom-button @click=\"handleClick\"\u003e\u003c/my-custom-button\u003e\n```\n\n**Build Output:**\n```html\n\u003cbutton class=\"close-button\" @click=\"handleClick\"\u003e\n    \u003csvg\u003e...\u003c/svg\u003e\n\u003c/button\u003e\n```\n\n✅ Events (`@click`) and bindings (`x-model`) are preserved and passed correctly.  \n\n---\n\n### 📦 **2. Default Attribute Mapping**\nIf your component has an element marked as `#default`, props are mapped automatically:\n\n**my-input.html**\n```html\n\u003cdiv\u003e\n    \u003cinput #default class=\"input-field\" /\u003e \n\u003c/div\u003e\n```\n\n**index.html**\n```html\n\u003cmy-input placeholder=\"Enter your email\" x-model=\"email\"\u003e\u003c/my-input\u003e\n```\n\n**Build Output:**\n```html\n\u003cdiv\u003e\n    \u003cinput class=\"input-field\" placeholder=\"Enter your email\" x-model=\"email\" /\u003e\n\u003c/div\u003e\n```\n\n✅ Clean, predictable prop mapping.  \n  \n**Details**\n- The root element of the component is automatically the `#default` if no other element within the component has a `#default` attribute\n\n---\n\n### 📦 **3. Named Slots with Target Mapping**\nMap specific child elements to targets in your components:\n\n**my-card.html**\n```html\n\u003cdiv class=\"card\"\u003e\n    \u003ch1 #title\u003e\u003c/h1\u003e\n    \u003cp #content\u003e\u003c/p\u003e\n\u003c/div\u003e\n```\n\n**index.html**\n```html\n\u003cmy-card\u003e\n    \u003ctitle\u003eThis is the Title\u003c/title\u003e\n    \u003ccontent\u003eThis is the Content\u003c/content\u003e\n\u003c/my-card\u003e\n```\n\n**Build Output:**\n```html\n\u003cdiv class=\"card\"\u003e\n    \u003ch1\u003eThis is the Title\u003c/h1\u003e\n    \u003cp\u003eThis is the Content\u003c/p\u003e\n\u003c/div\u003e\n```\n\n✅ Clear and intuitive named slot-like behavior.  \n\n---\n\n### 📦 **4. Scoped Styles**\nEach component’s styles are:\n- **Scoped to their usage** (avoiding global CSS pollution).  \n- **Automatically extracted into `component-styles.css`.**  \n\n✅ Styles only load when they’re needed.  \n\n---\n\n### 📦 **5. Nested Components**\nMesa supports **nested components** seamlessly:\n\n**nested-component.html**\n```html\n\u003cdiv class=\"nested\"\u003e\n    \u003cinner-component\u003e\u003c/inner-component\u003e\n\u003c/div\u003e\n```\n\n**index.html**\n```html\n\u003cnested-component\u003e\u003c/nested-component\u003e\n```\n\nMesa recursively processes inner components during the build phase.\n\n✅ Fully recursive parsing and transformation.  \n\n\n# 📚 **Getting Started**\n\n## 🚀 New Project\nSetup a new mesa project by running the command below, this sets you up with a sample website:\n\n```\nnpx @octamap/create-mesa@latest project-name\n```\n\n## 🤖 Add to existing project \n\n### 1️⃣ **Install Mesa**\n```bash\nnpm install @octamap/mesa --save-dev\n```\n\n### 2️⃣ **Configure Vite**\nUpdate your `vite.config.ts`:\n\n```typescript\nimport { defineConfig } from 'vite';\nimport { Mesa } from '@octamap/mesa';\n\nexport default defineConfig({\n  plugins: [\n    Mesa({\n        'my-custom-button': './src/components/my-custom-button.html',\n        'my-card': './src/components/my-card.html'\n    })\n  ]\n});\n```\n\n### 3️⃣ **Run Your Project**\n```bash\nnpm run dev\n```\n\n✅ Enjoy live-reloading and build-time transformations.  \n\n### 4️⃣ **Build for Production**\n```bash\nnpm run build\n```\n\n✅ Your components are compiled, styles extracted, and everything is optimized.  \n\n\n# ⚡️ Ultra quick hydration\n\nSvelte SSG has been the wholy grail of quick websites. With Mesa you achive this but even quicker. \n\n- SvelteKit SSG hydration involves loading the Svelte runtime and then essentially \"rebuilding\" the page’s structure by mapping pre-rendered HTML to its components.\n\n- Mesa achieves the same level of interactivity by allowing you to use lightweight frameworks like Alpine.js or HTMX, which operate directly on the DOM. These frameworks don’t need to rebuild the page’s structure—they simply bind functionality to the already-rendered HTML.\n\n### Comparison:\n\n| Feature                   | SvelteKit (SSG)              | Mesa + alpine.js             |\n| ------------------------- | ---------------------------- | --------------------- |\n| **Initial HTML Load**     | Instant                      | Instant               |\n| **JavaScript Payload**    | Medium (slightly larger)     | Small (lightweight)   |\n| **Hydration Speed**       | Slightly Slower              | Faster (no hydration) |\n| **Reactivity Setup Time** | Fast, but hydration required | Very Fast             |\n\n\n# 🤯 Compile Time JavaScript\n\nMesa allows you to use **JavaScript at build time** to dynamically generate static HTML. This means you can use logic like loops, conditions, and bindings during the build process, but the final output is fully-rendered, SEO-friendly, and lightning-fast HTML.\n\n### 🚀 **Getting Started with Compile-Time JavaScript**\n\n#### **1️⃣ Define Compile-Time Logic**\n\nUse the `\u003cscript #mesa\u003e` tag to write your JavaScript logic. This script runs only during the build process and is not included in the final output.\n\n```html\n\u003cscript #mesa\u003e\n  const items = [\"Home\", \"About\", \"Contact\"];\n\u003c/script\u003e\n```\n\n#### **2️⃣ Use the Variables in Your HTML**\n\nMesa's declarative syntax makes it easy to loop through data and dynamically generate HTML.\n\n```html\n\u003cul\u003e\n  \u003cli :for=\"item in items\"\u003e{{ item }}\u003c/li\u003e\n\u003c/ul\u003e\n```\n\n#### **3️⃣ Mesa Compiles the HTML**\n\nDuring the build, Mesa executes the `#mesa` script and replaces the dynamic logic with fully-rendered static HTML.\n\n---\n\n### ✅ **Simple Example: Dynamic List**\n\n#### **Input:**\n```html\n\u003cscript #mesa\u003e\n  const items = [\"Home\", \"About\", \"Contact\"];\n\u003c/script\u003e\n\u003cul\u003e\n  \u003cli :for=\"item in items\"\u003e{{ item }}\u003c/li\u003e\n\u003c/ul\u003e\n```\n\n#### **Output:**\n```html\n\u003cul\u003e\n  \u003cli\u003eHome\u003c/li\u003e\n  \u003cli\u003eAbout\u003c/li\u003e\n  \u003cli\u003eContact\u003c/li\u003e\n\u003c/ul\u003e\n```\n\nThis produces clean, static HTML without requiring any JavaScript at runtime.\n\n### ✅ **Dynamic Attributes and Event Bindings**\n\nYou can also bind attributes and events dynamically at build time.\n\n#### **Input:**\n```html\n\u003cscript #mesa\u003e\n  const buttons = [\n    { label: \"Save\", action: \"saveData()\" },\n    { label: \"Delete\", action: \"deleteData()\" },\n  ];\n\u003c/script\u003e\n\u003cdiv\u003e\n  \u003cbutton :for=\"button in buttons\" @click=\"button.action\"\u003e\n    {{ button.label }}\n  \u003c/button\u003e\n\u003c/div\u003e\n```\n\n#### **Output:**\n```html\n\u003cdiv\u003e\n  \u003cbutton @click=\"saveData()\"\u003eSave\u003c/button\u003e\n  \u003cbutton @click=\"deleteData()\"\u003eDelete\u003c/button\u003e\n\u003c/div\u003e\n```\n\n---\n\n### 🚀 **More Advanced Examples**\n\nOnce you're comfortable with the basics, you can use Mesa's compile-time JavaScript for more complex scenarios.\n\n#### **Dynamic Segments**\n\nUse `:for` loops and bindings to create interactive elements of a component called `segment-control`\n\n##### **Input:**\n```html\n\u003cscript #mesa\u003e\n  const segments = [\n    { name: \"Document Tools\", url: \"/videos/doc-tools.mov\" },\n    { name: \"3D Configurators\", url: \"/videos/configurators.mov\" },\n  ];\n\u003c/script\u003e\n\u003csegment-control\n  :for=\"(segment, index) in segments\"\n  @click=\"play(segment.url)\"\n  :class=\"{selected: index === selectedIndex}\"\u003e\n  {{ segment.name }}\n\u003c/segment-control\u003e\n```\n\n##### **Output:**\n```html\n\u003cdiv class=\"segment-control\"\u003e\n  \u003cbutton @click=\"play('/videos/doc-tools.mov')\" :class=\"{selected: 0 === selectedIndex}\"\u003e\n    Document Tools\n  \u003c/button\u003e\n  \u003cbutton @click=\"play('/videos/configurators.mov')\" :class=\"{selected: 1 === selectedIndex}\"\u003e\n    3D Configurators\n  \u003c/button\u003e\n\u003c/div\u003e\n```\n\n# 🚦 **Examples \u0026 Additional Features**\n\n## 📦 **Defining Components Outside of `vite.config.ts`**\n\nIn larger projects or when working with shared component libraries, managing all your component mappings directly inside `vite.config.ts` can become cumbersome. **Mesa** allows you to define components in an external JavaScript or TypeScript file using the `components` function.  \n\nThis approach ensures better **separation of concerns**, easier **reusability**, and improved **readability**.\n\n---\n\n### 🛠️ **Step 1: Create a Components Configuration File**\n\nCreate a file to define your components, for example:  \n\n### 📄 **components.ts**\n```typescript\nimport { components } from \"@octamap/mesa\";\n\n// Use import.meta.url to resolve absolute paths to component files\nconst OctamapHtmlComponents = components(import.meta.url, {\n    \"icon-field\": \"./src/icon-field.html\",\n    \"close-button\": \"./src/close-button.html\",\n    \"back-button\": \"./src/back-button.html\",\n    \"head-defaults\": \"./src/head-defaults.html\",\n});\n\nexport { OctamapHtmlComponents };\n```\n\n### ✅ **Why `import.meta.url` is Necessary?**  \nThe `import.meta.url` ensures that **Mesa can resolve absolute paths** to your HTML component files. Without it, the plugin might struggle to correctly locate your component files, especially when working across different environments or build pipelines.\n\n---\n\n### 🛠️ **Step 2: Use the Configuration in `vite.config.ts`**\n\nImport your component configuration into `vite.config.ts`:\n\n### 📄 **vite.config.ts**\n```typescript\nimport { defineConfig } from 'vite';\nimport { Mesa } from '@octamap/mesa';\nimport { OctamapHtmlComponents } from './components';\n\nexport default defineConfig({\n  plugins: [\n    Mesa(OctamapHtmlComponents)\n  ]\n});\n```\n\n---\n\n### 🧠 **How it Works**\n1. The `components` function maps component names (`icon-field`, `close-button`) to their respective HTML files (`icon-field.html`, `close-button.html`).  \n2. `import.meta.url` ensures **absolute paths** are resolved correctly at runtime.  \n3. `vite.config.ts` references these mappings via `OctamapHtmlComponents`.  \n\nThis approach keeps your `vite.config.ts` **clean and focused** while centralizing component definitions in a separate file.\n\n---\n\n### 📚 **Advantages of This Approach**\n✅ **Improved Maintainability:** Component mappings are easier to update and manage in one dedicated file.  \n✅ **Reusability:** The configuration can be reused across different projects or environments.  \n✅ **Scalability:** Large projects with hundreds of components are easier to organize.  \n✅ **Clear Separation:** `vite.config.ts` remains focused on build configuration.\n\n---\n\n\n### 📦 **Example Folder Structure**\n\n```\n/src\n  /components\n    icon-field.html\n    close-button.html\n    back-button.html\n    head-defaults.html\n  /scripts\n    components.ts     \u003c-- Define component mappings here\nvite.config.ts        \u003c-- Reference the mappings\n```\n\n## 📂 **Register Entire Folders of Components with `folder`**\n\n### 🚀 **Simplify Component Registration with `folder`**\n\nMesa now supports **bulk registration** of `.html` or `.svg` components from an entire folder using the `folder` function. This makes it incredibly easy to manage and include multiple components without manually defining each one in your configuration.\n\n---\n\n### 🛠️ **1. Folder-Based Component Registration**\n\nYou can register all `.html` and `.svg` components in a folder using the `folder` utility:\n\n**vite.config.ts**\n```typescript\nimport { defineConfig } from 'vite';\nimport { Mesa, folder } from '@octamap/mesa';\nimport { OctamapHtmlComponents } from './components';\n\nexport default defineConfig({\n  plugins: [\n    Mesa({\n      ...OctamapHtmlComponents,\n      ...folder(\"./icons\") // Registers all components in the ./icons folder\n    }),\n  ],\n});\n```\n\n✅ The `folder` function scans the `./icons` directory and registers all `.html` and `.svg` files as components.  \n✅ Nested folders are supported, and components are named based on their folder structure.\n\n---\n\n### 📂 **2. Folder Structure Example**\n\nYour project might have a folder structure like this:\n\n```\n/icons\n  letter-notification.svg\n  /another-folder\n    profile-icon.svg\n```\n\n---\n\n### 📄 **3. Use Registered Components in HTML**\n\nAfter registering the folder, you can use the components directly in your HTML:\n\n**index.html**\n```html\n\u003cdiv\u003e\n    \u003cdiv class=\"check-inbox-page\"\u003e\n        \u003cletter-notification height=\"60px\"\u003e\u003c/letter-notification\u003e\n        \u003canother-folder-profile-icon\u003e\u003c/another-folder-profile-icon\u003e\n    \u003c/div\u003e\n\u003c/div\u003e\n```\n\n✅ **Automatic Naming:**  \n- `letter-notification.svg` → `\u003cletter-notification\u003e`  \n- `another-folder/profile-icon.svg` → `\u003canother-folder-profile-icon\u003e`  \n\n✅ **Scoped Naming:** Nested folder structures are preserved in the component names to avoid conflicts.\n\n---\n\n### 🧠 **How it Works**\n1. The `folder` function scans the specified directory.\n2. Each `.html` and `.svg` file is registered as a Mesa component.\n3. Nested files are automatically prefixed with their folder names.\n\n**Example Naming Convention:**  \n- `icons/alert.svg` → `\u003calert\u003e`  \n- `icons/notifications/alert.svg` → `\u003cnotifications-alert\u003e`  \n\nThis ensures unique and collision-free component names.\n\nWith `folder`, managing and scaling your components becomes effortless. Say goodbye to repetitive mappings and enjoy clean, intuitive configurations. 🚀✨\n\n---\n\nHere's an illustrative section explaining how Mesa handles **scoped styles for components** and ensures they are appropriately applied regardless of where the component is used:\n\n---\n\n## 📦 **Scoped Styles Across Different Usage Scenarios**\n\nMesa ensures **scoped styles** are applied consistently across your components, whether they're used in a **single page** or **multiple pages**.\n\n### 📄 **1. Component Definition**\n\nFirst, define your reusable component with its styles.\n\n**📂 letter-notification.svg**\n```html\n\u003csvg\u003e\n  ..\n\u003c/svg\u003e\n```\n\n**📂 check-inbox.html**\n```html\n\u003cdiv\u003e\n    \u003cdiv class=\"check-inbox-page\"\u003e\n        \u003cletter-notification height=\"60px\"\u003e\u003c/letter-notification\u003e\n    \u003c/div\u003e\n\u003c/div\u003e\n\n\u003cstyle\u003e\n.check-inbox-page {\n    height: 100px;\n    width: 200px;\n}\n\u003c/style\u003e\n```\n\n---\n\n### 📄 **2. Using the Component in `index.html`**\n\nWhen the component is used in a dedicated page, Mesa extracts and consolidates its styles into a global stylesheet (`component-styles.css`).\n\n**📂 index.html**\n```html\n\u003cbody\u003e\n    \u003ccheck-inbox\u003e\u003c/check-inbox\u003e\n\u003c/body\u003e\n```\n\n**🔄 Build Output:**\n```html\n\u003chead\u003e\n    \u003clink rel=\"stylesheet\" href=\"/component-styles.css\"\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003cdiv class=\"check-inbox-page\"\u003e\n        \u003csvg\u003e .. \u003c/svg\u003e\n    \u003c/div\u003e\n\u003c/body\u003e\n```\n\n**📂 component-styles.css**\n```css\n.check-inbox-page {\n    height: 100px;\n    width: 200px;\n}\n```\n\n✅ **Global styles ensure optimized loading** for dedicated pages.\n\n---\n\n### 📄 **3. Using the Component in Another Page (`some-page.html`)**\n\nWhen the same component is used **outside of its primary context** (e.g., `some-page.html`), Mesa intelligently inlines the required styles to prevent missing styles or dependency on global CSS.\n\n**📂 some-page.html**\n```html\n\u003cdiv\u003e\n    \u003ccheck-inbox\u003e\u003c/check-inbox\u003e\n\u003c/div\u003e\n```\n\n**🔄 Build Output:**\n```html\n\u003cdiv\u003e\n    \u003cstyle\u003e\n        .check-inbox-page {\n            height: 100px;\n            width: 200px;\n        }\n    \u003c/style\u003e\n    \u003cdiv class=\"check-inbox-page\"\u003e\n        \u003csvg\u003e .. \u003c/svg\u003e\n    \u003c/div\u003e\n\u003c/div\u003e\n```\n\n✅ **Inline styles guarantee isolation** and ensure the component renders consistently even without global styles.\n\n---\n\n# 📚 **Advanced Example: Multi-Package Integration with Mesa**\n\nIn this example, we'll explore how **Mesa** enables seamless integration between separate packages for **SVG icons** and **web components**, allowing clean, reusable, and optimized component architecture.\n\n---\n\n## 🚀 **Scenario Overview**\n\nWe have two npm packages:\n\n1. **oicon** – A package containing SVG icons.  \n2. **components** – A package containing reusable UI components, including one that uses icons from **oicon**.\n\n### 📂 **1. oicon Package**\n\n```plaintext\noicon/\n├── package.json\n├── index.ts\n└── src/\n    ├── chevron-left.svg\n    ├── checkmark.svg\n```\n\n#### 📄 **index.ts**\n\n```typescript\nimport { folder } from '@octamap/mesa';\n\nconst OIconComponents = folder(\"./src/\", {\n    importMetaUrl: import.meta.url, // Ensures Mesa resolves the correct paths\n    prefix: \"oicon\" // Enables usage as \u003coicon-chevron-left /\u003e\n});\n\nexport { OIconComponents };\n```\n\nWith this setup:\n- Icons are accessible via `\u003coicon-chevron-left /\u003e` and `\u003coicon-checkmark /\u003e`.\n\n---\n\n### 📂 **2. Components Package**\n\n```plaintext\ncomponents/\n├── package.json\n├── index.ts\n└── src/\n    └── back-button.html\n```\n\n#### 📄 **back-button.html**\n\n```html\n\u003cbutton class=\"top-left-back\"\u003e\n    \u003coicon-chevron-left\u003e\u003c/oicon-chevron-left\u003e\n\u003c/button\u003e\n\n\u003cstyle\u003e\n.top-left-back {\n    position: fixed;\n    left: 30px;\n    top: 30px;\n    --diameter: 55px;\n    height: var(--diameter);\n    width: var(--diameter);\n    display: flex;\n    align-items: center;\n    justify-content: center;\n    border-radius: 100em;\n    border: none;\n    outline: solid 1px var(--line-color);\n    background-color: white;\n    cursor: pointer;\n}\n\u003c/style\u003e\n```\n\nHere:\n- The **Back Button** component references `\u003coicon-chevron-left\u003e`.\n\n#### 📄 **index.ts**\n\n```typescript\nimport { folder } from '@octamap/mesa';\n\nconst Components = folder(\"./src/\", {\n    importMetaUrl: import.meta.url, // Correct path resolution\n});\n\nexport { Components };\n```\n\n---\n\n### 📂 **3. Main Project Integration**\n\nNow, let's integrate these packages into our **Vite** configuration.\n\n#### 📄 **vite.config.ts**\n\n```typescript\nimport { defineConfig } from 'vite';\nimport { Mesa } from '@octamap/mesa';\nimport { OIconComponents } from '@your-package/oicon';\nimport { Components } from '@your-package/components';\n\nexport default defineConfig({\n  plugins: [\n    Mesa({\n      ...OIconComponents,\n      ...Components,\n    }),\n  ],\n});\n```\n\n---\n\n### 📂 **4. Using Components in Your Project**\n\nLet's create a `check-inbox.html` page.\n\n#### 📄 **check-inbox.html**\n\n```html\n\u003cdiv class=\"check-inbox-page\"\u003e\n    \u003cback-button @click=\"closeCheckInbox()\"\u003e\u003c/back-button\u003e\n\u003c/div\u003e\n\n\u003cstyle\u003e\n.check-inbox-page {\n    display: flex;\n    flex-direction: column;\n    align-items: center;\n    position: absolute;\n    left: 0;\n    top: 0;\n    height: 100vh;\n    width: 100vw;\n    z-index: 100;\n}\n\u003c/style\u003e\n```\n\n**Mesa Handles:**\n1. **Scoped Styles** – `check-inbox-page` and `top-left-back` styles are scoped and applied correctly.\n2. **Lazy Loading** – `check-inbox.html` styles are inlined only when the page is loaded.\n3. **Optimized Rendering** – No unnecessary CSS in your `index.html`.\n\n---\n\n## 🪄 **How Mesa Optimizes Your Build**\n\nWhen a user navigates to `check-inbox.html`:\n\n1. The router dynamically loads `check-inbox.html`.  \n2. Mesa inlines the required CSS for `.check-inbox-page` and `.top-left-back`.  \n3. SVG content is embedded in the `\u003cback-button\u003e` component.\n\n**Resulting HTML:**\n\n```html\n\u003cdiv class=\"check-inbox-page\"\u003e\n    \u003cbutton class=\"top-left-back\" @click=\"closeCheckInbox()\"\u003e\n        \u003csvg viewBox=\"0 0 11 20\" xmlns=\"http://www.w3.org/2000/svg\"\u003e\n            \u003cpath d=\"M9.216,1.369l-7.847,8.627l7.847,8.628\"\n                style=\"fill:#fff;stroke:currentColor;stroke-width:2.74px;\"\u003e\u003c/path\u003e\n        \u003c/svg\u003e\n    \u003c/button\u003e\n\u003c/div\u003e\n\n\u003cstyle\u003e\n.check-inbox-page {\n    display: flex;\n    flex-direction: column;\n    align-items: center;\n    position: absolute;\n    left: 0;\n    top: 0;\n    height: 100vh;\n    width: 100vw;\n    z-index: 100;\n}\n\n.top-left-back {\n    position: fixed;\n    left: 30px;\n    top: 30px;\n    --diameter: 55px;\n    height: var(--diameter);\n    width: var(--diameter);\n    display: flex;\n    align-items: center;\n    justify-content: center;\n    border-radius: 100em;\n    border: none;\n    outline: solid 1px var(--line-color);\n    background-color: white;\n    cursor: pointer;\n}\n\u003c/style\u003e\n```\n\n---\n\n### 🧠 **How Mesa Manages Scoped Styles:**\n\n1. **Global Styles:** For components used consistently across an entire page, styles are extracted into `component-styles.css`.\n2. **Inline Styles:** When components are used in isolated contexts or ad-hoc pages, Mesa inlines the necessary styles directly.\n\n✅ **No CSS leakage across components.**  \n✅ **Optimal performance with minimal style duplication.**  \n✅ **Scoped styles ensure predictable rendering.**\n\n# 📖 **Documentation \u0026 Examples**\n\n- **Full Documentation:** [Coming Soon]  \n- **Starter Templates:** [Coming Soon]  \n- **Live Demo Projects:** [Coming Soon]  \n\n---\n\n# 🧠 **Why Mesa?**\n\n✅ **Static-first:** Everything is rendered at build time.  \n✅ **SEO-friendly:** Full markup available to crawlers.  \n✅ **No runtime overhead:** Zero JavaScript parsing for rendering components.  \n✅ **Scalable:** Perfect for micro-frontends and component-based architectures.  \n✅ **Framework-agnostic:** Use with Alpine.js, HTMX, or vanilla JS.  \n\n---\n\n# ❤️ **Join the Community**\n- GitHub: https://github.com/octamap/mesa\n\n\n**Let’s redefine the way we build HTML components.** 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctamap%2Fmesa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foctamap%2Fmesa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctamap%2Fmesa/lists"}