feat-flag-drupal 0.0.4 → 0.1.1

package/README.md

@@ -4,10 +4,12 @@ This project is a simple versioning system for web assets. It uses Vite to bundl
 
 ## Development vs. Production
 
-This project has two main modes:
+This project has multiple build modes:
 
-*   **Development (`npm run dev`):** Uses a standard `index.html` file for a fast and reliable development experience with Hot Module Replacement (HMR).
-*   **Production Build (`npm run build`):** Uses `index.twig` as the source, compiles it to HTML, and generates versioned assets in the `build/` directory.
+*   **Development with HMR (`npm run dev`):** Uses a standard `index.html` file for a fast development experience with Hot Module Replacement.
+*   **Development Build (`npm run dev:build`):** Rebuilds the current version without incrementing - useful for testing changes to the latest version.
+*   **Production Build (`npm run build`):** Rebuilds the current version (same as `dev:build`).
+*   **Create New Version (`npm run build:version`):** Increments the version and creates new versioned assets.
 
 ## How to Use
 
@@ -17,33 +19,47 @@ This project has two main modes:
     ```
 
 2.  **Develop your application:**
-    *   Run `npm run dev`.
+    *   Run `npm run dev` for live development with HMR.
     *   Make changes to your assets in the `src/` directory.
     *   The browser will automatically update as you save files.
 
-3.  **Prepare for production:**
-    *   Modify `index.twig` to structure your final production HTML. You can use Twig syntax here.
+3.  **Test your changes:**
+    *   Run `npm run dev:build` or `npm run build` to rebuild the current version.
+    *   This lets you test the production build without creating a new version.
 
-4.  **Build a new version:**
-    *   When you are ready to create a new version of your assets, run the following command:
+4.  **Create a new version:**
+    *   When you are ready to release a new version, run:
     ```bash
-    npm run build
+    npm run build:version
     ```
+    *   This will increment the patch version and create new versioned assets.
 
 ## How the Build Process Works
 
-The `npm run build` command does the following:
+### Rebuilding Current Version (`npm run build` or `npm run dev:build`)
 
-1.  **Determines New Version:** It checks for a `build/manifest.json`. If it exists, it increments the `latest_version` number to create a new version. If not, it uses the version from `package.json`. The `package.json` file itself is not modified.
-2.  **Builds Assets:** It runs Vite to build and bundle your assets, compiling your `index.twig` file into a final `index.html`.
-3.  **Outputs Versioned Files:** The output files are placed in the `build/` directory. The filenames will include the new version number, for example:
+These commands rebuild the current version without incrementing:
+
+1.  **Uses Current Version:** Reads the `latest_version` from `build/manifest.json` (or `package.json` if no manifest exists).
+2.  **Builds Assets:** Runs Vite to build and bundle your assets.
+3.  **Outputs Versioned Files:** Overwrites the existing versioned files in the `build/` directory.
+4.  **Updates Manifest:** Updates the manifest entry for the current version.
+
+Use this during development when you want to iterate on the current version without creating new version numbers.
+
+### Creating New Version (`npm run build:version`)
+
+This command creates a new version:
+
+1.  **Increments Version:** Reads `latest_version` from `build/manifest.json` and increments the patch number (e.g., 0.0.1 → 0.0.2).
+2.  **Builds Assets:** Runs Vite to build and bundle your assets.
+3.  **Outputs Versioned Files:** Creates new files with the incremented version number:
     *   `main-0.0.2.js`
     *   `style-0.0.2.css`
-4.  **Generates a Manifest:** It creates or updates a `build/manifest.json` file.
+4.  **Updates Manifest:** Adds the new version to `build/manifest.json` and updates `latest_version`.
 
-## Twig Support
+Use this when you're ready to release a new version to production.
 
-This project uses `vite-plugin-twig-drupal` to compile `.twig` files during the **build process only**. You can write your final production markup in `index.twig` and it will be compiled to `index.html` in the `build` directory.
 
 ## Feature Flagging and the Manifest
 
@@ -69,8 +85,126 @@ Here is an example of the manifest structure:
 
 Your feature flagging system can consume this file to dynamically load the correct assets for a given version.
 
-## Publishing as an NPM Package
 
-This project is set up to be published as an NPM package. The `files` property in `package.json` is configured to only include the `build` directory when you publish the package.
+# Integrating Version Builder with a Drupal Theme
+
+This guide explains how to integrate the `version-builder` project into a Drupal theme to manage versioned CSS and JavaScript assets.
+
+### 1. Place Your Project Inside Your Drupal Theme
+
+Move your entire `version-builder` project into a subdirectory within your Drupal theme. For example:
+
+```
+/themes/custom/my_theme/
+├── my_theme.info.yml
+├── my_theme.libraries.yml
+├── my_theme.theme
+├── css/
+├── js/
+├── templates/
+└── version-builder/  <-- Your project goes here
+    ├── src/
+    ├── build/
+    ├── scripts/
+    ├── package.json
+    └── ...
+```
+
+### 2. The Build Process
+
+Your build process remains the same. You will navigate into the `version-builder` directory and run the build command:
+
+```bash
+cd /path/to/your/theme/version-builder
+npm run build
+```
+
+This will generate the versioned assets and the `manifest.json` inside `/themes/custom/my_theme/version-builder/build/`.
+
+### 3. Integrate with Drupal's Library System
+
+This is the most critical part. You need to make Drupal aware of your versioned files. You'll do this by dynamically reading the `manifest.json` and telling Drupal which files to load.
+
+**A. Define a placeholder library in `my_theme.libraries.yml`:**
+
+Create a library entry that you will override dynamically.
+
+```yaml
+# my_theme.libraries.yml
+versioned-assets:
+  js:
+    # This is just a placeholder. It will be replaced.
+    js/placeholder.js: {}
+  css:
+    # This is just a placeholder. It will be replaced.
+    theme:
+      css/placeholder.css: {}
+```
+
+**B. Read the manifest and alter the library in `my_theme.theme`:**
+
+You'll use a hook, like `hook_page_attachments_alter`, to read your `manifest.json` and swap out the placeholder assets with the real, versioned ones.
+
+```php
+<?php
+// my_theme.theme
+
+/**
+ * Implements hook_page_attachments_alter().
+ */
+function my_theme_page_attachments_alter(array &$attachments) {
+  // 1. Decide which version to load.
+  // This is where your feature flagging logic goes. For example, you could use a query
+  // parameter, a config setting, or check the user's role.
+  // For this example, we'll just load the 'latest_version'.
+  $version_to_load = NULL;
+
+  // 2. Read and parse the manifest.json.
+  $manifest_path = \Drupal::service('extension.path.resolver')->getPath('theme', 'my_theme') . '/version-builder/build/manifest.json';
+  if (file_exists($manifest_path)) {
+    $manifest = json_decode(file_get_contents($manifest_path), TRUE);
+
+    // Get the version key from your logic.
+    $version_to_load = $manifest['latest_version']; // Or get from a feature flag service.
+
+    if (isset($manifest['versions'][$version_to_load])) {
+      $assets = $manifest['versions'][$version_to_load];
+
+      // 3. Dynamically override the library definition.
+      // The key 'my_theme/versioned-assets' matches the library defined in your .libraries.yml file.
+      $attachments['#attached']['library']['my_theme/versioned-assets'] = [
+        'js' => [
+          // The path is relative to your Drupal root.
+          'themes/custom/my_theme/version-builder/build' . $assets['main.js'] => [],
+        ],
+        'css' => [
+          'theme' => [
+            'themes/custom/my_theme/version-builder/build' . $assets['style.css'] => [],
+          ],
+        ],
+      ];
+    }
+  }
+}
+```
+
+### 4. Attach the Library in Your Twig Templates
+
+Finally, in your Drupal theme's Twig templates (e.g., `page.html.twig`), you attach the library as you normally would.
+
+```twig
+{# templates/page.html.twig #}
+
+{{ attach_library('my_theme/versioned-assets') }}
+
+<div class="page-content">
+  ...
+</div>
+```
+
+### Summary of the Workflow
 
-The `main` entry in `package.json` points to `build/main.js`. After running a build, the actual filename will be versioned (e.g., `build/main-0.0.2.js`). You may need to adjust your package consumption logic to account for the versioned filenames.
+1.  You work on your assets inside the `version-builder/src` directory.
+2.  You run `npm run build` to create a new, versioned set of assets and update the `manifest.json`.
+3.  When a user visits your Drupal site, the `my_theme.theme` file reads the manifest, determines which version to show based on your feature flagging logic, and tells Drupal the exact CSS and JS files to load for that version.
+4.  Drupal attaches those specific, versioned files to the page.

package/build/main-0.1.1.js

@@ -0,0 +1 @@
+document.addEventListener("DOMContentLoaded",()=>{const e=document.getElementById("app");e.textContent="Hello from version-builder!"});

package/build/manifest.json

@@ -1,17 +1,13 @@
 {
   "versions": {
-    "0.0.4": {
-      "main.js": "/main-0.0.4.js",
-      "style.css": "/style-0.0.4.css"
+    "0.1.0": {
+      "main.js": "/main-0.1.0.js",
+      "style.css": "/style-0.1.0.css"
     },
-    "0.0.5": {
-      "main.js": "/main-0.0.5.js",
-      "style.css": "/style-0.0.5.css"
-    },
-    "0.0.6": {
-      "main.js": "/main-0.0.6.js",
-      "style.css": "/style-0.0.6.css"
+    "0.1.1": {
+      "main.js": "/main-0.1.1.js",
+      "style.css": "/style-0.1.1.css"
     }
   },
-  "latest_version": "0.0.6"
+  "latest_version": "0.1.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feat-flag-drupal",
-  "version": "0.0.4",
+  "version": "0.1.1",
   "private": false,
   "main": "build/main.js",
   "files": [
@@ -9,11 +9,15 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
+    "dev:build": "node scripts/dev-build.js",
     "build": "node scripts/build.js",
+    "build:version": "node scripts/version.js",
     "preview": "vite preview"
   },
   "devDependencies": {
     "sass-embedded": "^1.98.0",
     "vite": "^7.0.0"
-  }
+  },
+  "license": "MIT",
+  "description": "A tool to build and manage versioned assets for Drupal themes, enabling feature flagging and A/B testing."
 }

package/build/main-0.0.4.js

@@ -1,66 +0,0 @@
-/* empty css           */document.querySelector("#app").innerHTML=`
-<pre>
-<code>
-# Version Builder
-
-This project is a simple versioning system for web assets. It uses Vite to bundle your code and a custom script to automatically increment the version number with each build.
-
-## How to Use
-
-1.  **Place your code:** Put your HTML, CSS, JavaScript, and other asset files in the root directory of the project. The main entry point for the application is \`index.html\`.
-
-2.  **Install dependencies:**
-    \`\`\`bash
-    npm install
-    \`\`\`
-
-3.  **Modify your code:** Make any changes you need to your source files.
-
-4.  **Build a new version:** When you are ready to create a new version of your assets, run the following command:
-    \`\`\`bash
-    npm run build
-    \`\`\`
-
-## How it Works
-
-The \`npm run build\` command does the following:
-
-1.  **Increments Version:** It automatically increments the \`patch\` number (the last digit) of the version in \`package.json\`. For example, \`0.0.1\` becomes \`0.0.2\`.
-2.  **Builds Assets:** It runs Vite to build and bundle your assets.
-3.  **Outputs Versioned Files:** The output files are placed in the \`build/\` directory. The filenames will include the new version number, for example:
-    *   \`main-0.0.2.js\`
-    *   \`style-0.0.2.css\`
-4.  **Generates a Manifest:** It creates or updates a \`build/manifest.json\` file.
-
-## Feature Flagging and the Manifest
-
-To support feature flagging systems, the build process generates a \`manifest.json\` file. This file acts as a single source of truth for your system to look up which assets belong to which version.
-
-Here is an example of the manifest structure:
-
-\`\`\`json
-{
-  "versions": {
-    "0.0.1": {
-      "main.js": "/main-0.0.1.js",
-      "style.css": "/style-0.0.1.css"
-    },
-    "0.0.2": {
-      "main.js": "/main-0.0.2.js",
-      "style.css": "/style-0.0.2.css"
-    }
-  },
-  "latest_version": "0.0.2"
-}
-\`\`\`
-
-Your feature flagging system can consume this file to dynamically load the correct assets for a given version.
-
-## Publishing as an NPM Package
-
-This project is set up to be published as an NPM package. The \`files\` property in \`package.json\` is configured to only include the \`build\` directory when you publish the package.
-
-The \`main\` entry in \`package.json\` points to \`build/main.js\`. After running a build, the actual filename will be versioned (e.g., \`build/main-0.0.2.js\`). You may need to adjust your package consumption logic to account for the versioned filenames.
-</code>
-</pre>
-`;

package/build/main-0.0.5.js

@@ -1,66 +0,0 @@
-document.querySelector("#app").innerHTML=`
-<pre>
-<code>
-# Version Builder
-
-This project is a simple versioning system for web assets. It uses Vite to bundle your code and a custom script to automatically increment the version number with each build.
-
-## How to Use
-
-1.  **Place your code:** Put your HTML, CSS, JavaScript, and other asset files in the root directory of the project. The main entry point for the application is \`index.html\`.
-
-2.  **Install dependencies:**
-    \`\`\`bash
-    npm install
-    \`\`\`
-
-3.  **Modify your code:** Make any changes you need to your source files.
-
-4.  **Build a new version:** When you are ready to create a new version of your assets, run the following command:
-    \`\`\`bash
-    npm run build
-    \`\`\`
-
-## How it Works
-
-The \`npm run build\` command does the following:
-
-1.  **Increments Version:** It automatically increments the \`patch\` number (the last digit) of the version in \`package.json\`. For example, \`0.0.1\` becomes \`0.0.2\`.
-2.  **Builds Assets:** It runs Vite to build and bundle your assets.
-3.  **Outputs Versioned Files:** The output files are placed in the \`build/\` directory. The filenames will include the new version number, for example:
-    *   \`main-0.0.2.js\`
-    *   \`style-0.0.2.css\`
-4.  **Generates a Manifest:** It creates or updates a \`build/manifest.json\` file.
-
-## Feature Flagging and the Manifest
-
-To support feature flagging systems, the build process generates a \`manifest.json\` file. This file acts as a single source of truth for your system to look up which assets belong to which version.
-
-Here is an example of the manifest structure:
-
-\`\`\`json
-{
-  "versions": {
-    "0.0.1": {
-      "main.js": "/main-0.0.1.js",
-      "style.css": "/style-0.0.1.css"
-    },
-    "0.0.2": {
-      "main.js": "/main-0.0.2.js",
-      "style.css": "/style-0.0.2.css"
-    }
-  },
-  "latest_version": "0.0.2"
-}
-\`\`\`
-
-Your feature flagging system can consume this file to dynamically load the correct assets for a given version.
-
-## Publishing as an NPM Package
-
-This project is set up to be published as an NPM package. The \`files\` property in \`package.json\` is configured to only include the \`build\` directory when you publish the package.
-
-The \`main\` entry in \`package.json\` points to \`build/main.js\`. After running a build, the actual filename will be versioned (e.g., \`build/main-0.0.2.js\`). You may need to adjust your package consumption logic to account for the versioned filenames.
-</code>
-</pre>
-`;

package/build/style-0.0.6.css

@@ -1 +0,0 @@
-:root{--text: #6b6375;--text-h: #08060d;--bg: #fff;--border: #e5e4e7;--code-bg: #f4f3ec;--accent: #aa3bff;--accent-bg: rgba(170, 59, 255, .1);--accent-border: rgba(170, 59, 255, .5);--social-bg: rgba(244, 243, 236, .5);--shadow: rgba(0, 0, 0, .1) 0 10px 15px -3px, rgba(0, 0, 0, .05) 0 4px 6px -2px;--sans: system-ui, "Segoe UI", Roboto, sans-serif;--heading: system-ui, "Segoe UI", Roboto, sans-serif;--mono: ui-monospace, Consolas, monospace;font:18px/145% var(--sans);letter-spacing:.18px;color-scheme:light dark;color:var(--text);background:var(--bg);font-synthesis:none;text-rendering:optimizeLegibility;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}@media(max-width:1024px){:root{font-size:16px}}@media(prefers-color-scheme:dark){:root{--text: #9ca3af;--text-h: #f3f4f6;--bg: #16171d;--border: #2e303a;--code-bg: #1f2028;--accent: #c084fc;--accent-bg: rgba(192, 132, 252, .15);--accent-border: rgba(192, 132, 252, .5);--social-bg: rgba(47, 48, 58, .5);--shadow: rgba(0, 0, 0, .4) 0 10px 15px -3px, rgba(0, 0, 0, .25) 0 4px 6px -2px}#social .button-icon{filter:invert(1) brightness(2)}}body{margin:0}h1,h2{font-family:var(--heading);font-weight:500;color:var(--text-h)}h1{font-size:56px;letter-spacing:-1.68px;margin:32px 0}@media(max-width:1024px){h1{font-size:36px;margin:20px 0}}h2{font-size:24px;line-height:118%;letter-spacing:-.24px;margin:0 0 8px}@media(max-width:1024px){h2{font-size:20px}}p{margin:0}code{font-family:var(--mono);display:flex;flex-wrap:wrap;border-radius:4px;max-width:80vw;color:var(--text-h);overflow-x:auto}code{font-size:15px;line-height:135%;padding:4px 8px;background:var(--code-bg)}.counter{font-size:16px;padding:5px 10px;border-radius:5px;color:var(--accent);background:var(--accent-bg);border:2px solid transparent;transition:border-color .3s;margin-bottom:24px}.counter:hover{border-color:var(--accent-border)}.counter:focus-visible{outline:2px solid var(--accent);outline-offset:2px}.hero{position:relative}.hero .base,.hero .framework,.hero .vite{inset-inline:0;margin:0 auto}.hero .base{width:170px;position:relative;z-index:0}.hero .framework,.hero .vite{position:absolute}.hero .framework{z-index:1;top:34px;height:28px;transform:perspective(2000px) rotate(300deg) rotateX(44deg) rotateY(39deg) scale(1.4)}.hero .vite{z-index:0;top:107px;height:26px;width:auto;transform:perspective(2000px) rotate(300deg) rotateX(40deg) rotateY(39deg) scale(.8)}#app{max-width:100%;margin:0 auto;border-inline:1px solid var(--border);min-height:100svh;display:flex;flex-direction:column;box-sizing:border-box}#center{display:flex;flex-direction:column;gap:25px;place-content:center;place-items:center;flex-grow:1}@media(max-width:1024px){#center{padding:32px 20px 24px;gap:18px}}#next-steps{display:flex;border-top:1px solid var(--border);text-align:left}#next-steps>div{flex:1 1 0;padding:32px}@media(max-width:1024px){#next-steps>div{padding:24px 20px}}#next-steps .icon{margin-bottom:16px;width:22px;height:22px}@media(max-width:1024px){#next-steps{flex-direction:column;text-align:center}}#docs{border-right:1px solid var(--border)}@media(max-width:1024px){#docs{border-right:none;border-bottom:1px solid var(--border)}}#next-steps ul{list-style:none;padding:0;display:flex;gap:8px;margin:32px 0 0}#next-steps ul .logo{height:18px}#next-steps ul a{color:var(--text-h);font-size:16px;border-radius:6px;background:var(--social-bg);display:flex;padding:6px 12px;align-items:center;gap:8px;text-decoration:none;transition:box-shadow .3s}#next-steps ul a:hover{box-shadow:var(--shadow)}#next-steps ul a .button-icon{height:18px;width:18px}@media(max-width:1024px){#next-steps ul{margin-top:20px;flex-wrap:wrap;justify-content:center}#next-steps ul li{flex:1 1 calc(50% - 8px)}#next-steps ul a{width:100%;justify-content:center;box-sizing:border-box}}#spacer{height:88px;border-top:1px solid var(--border)}@media(max-width:1024px){#spacer{height:48px}}.ticks{position:relative;width:100%}.ticks:before,.ticks:after{content:"";position:absolute;top:-4.5px;border:5px solid transparent}.ticks:before{left:0;border-left-color:var(--border)}.ticks:after{right:0;border-right-color:var(--border)}