feat-flag-drupal 0.0.4 → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +124 -9
- package/build/main-0.0.7.js +1 -0
- package/build/manifest.json +5 -1
- package/build/style-0.0.7.css +1 -0
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -6,8 +6,8 @@ This project is a simple versioning system for web assets. It uses Vite to bundl
|
|
|
6
6
|
|
|
7
7
|
This project has two main modes:
|
|
8
8
|
|
|
9
|
-
* **Development (`npm run dev`):** Uses a standard `index.html` file for a fast and reliable development experience with Hot Module Replacement (HMR).
|
|
10
|
-
* **Production Build (`npm run build`):**
|
|
9
|
+
* **Development (`npm run dev`):** Uses a standard `index.html` file for a fast and reliable development experience with Hot Module Replacement (HMR). (For testing only)
|
|
10
|
+
* **Production Build (`npm run build`):** Generates versioned assets in the `build/` directory.
|
|
11
11
|
|
|
12
12
|
## How to Use
|
|
13
13
|
|
|
@@ -22,7 +22,7 @@ This project has two main modes:
|
|
|
22
22
|
* The browser will automatically update as you save files.
|
|
23
23
|
|
|
24
24
|
3. **Prepare for production:**
|
|
25
|
-
*
|
|
25
|
+
* You will want to name the twig file to match the desired drupal asset such as `page.html.twig` or any other
|
|
26
26
|
|
|
27
27
|
4. **Build a new version:**
|
|
28
28
|
* When you are ready to create a new version of your assets, run the following command:
|
|
@@ -41,9 +41,6 @@ The `npm run build` command does the following:
|
|
|
41
41
|
* `style-0.0.2.css`
|
|
42
42
|
4. **Generates a Manifest:** It creates or updates a `build/manifest.json` file.
|
|
43
43
|
|
|
44
|
-
## Twig Support
|
|
45
|
-
|
|
46
|
-
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.
|
|
47
44
|
|
|
48
45
|
## Feature Flagging and the Manifest
|
|
49
46
|
|
|
@@ -69,8 +66,126 @@ Here is an example of the manifest structure:
|
|
|
69
66
|
|
|
70
67
|
Your feature flagging system can consume this file to dynamically load the correct assets for a given version.
|
|
71
68
|
|
|
72
|
-
## Publishing as an NPM Package
|
|
73
69
|
|
|
74
|
-
|
|
70
|
+
# Integrating Version Builder with a Drupal Theme
|
|
71
|
+
|
|
72
|
+
This guide explains how to integrate the `version-builder` project into a Drupal theme to manage versioned CSS and JavaScript assets.
|
|
73
|
+
|
|
74
|
+
### 1. Place Your Project Inside Your Drupal Theme
|
|
75
|
+
|
|
76
|
+
Move your entire `version-builder` project into a subdirectory within your Drupal theme. For example:
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
/themes/custom/my_theme/
|
|
80
|
+
├── my_theme.info.yml
|
|
81
|
+
├── my_theme.libraries.yml
|
|
82
|
+
├── my_theme.theme
|
|
83
|
+
├── css/
|
|
84
|
+
├── js/
|
|
85
|
+
├── templates/
|
|
86
|
+
└── version-builder/ <-- Your project goes here
|
|
87
|
+
├── src/
|
|
88
|
+
├── build/
|
|
89
|
+
├── scripts/
|
|
90
|
+
├── package.json
|
|
91
|
+
└── ...
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### 2. The Build Process
|
|
95
|
+
|
|
96
|
+
Your build process remains the same. You will navigate into the `version-builder` directory and run the build command:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
cd /path/to/your/theme/version-builder
|
|
100
|
+
npm run build
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
This will generate the versioned assets and the `manifest.json` inside `/themes/custom/my_theme/version-builder/build/`.
|
|
104
|
+
|
|
105
|
+
### 3. Integrate with Drupal's Library System
|
|
106
|
+
|
|
107
|
+
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.
|
|
108
|
+
|
|
109
|
+
**A. Define a placeholder library in `my_theme.libraries.yml`:**
|
|
110
|
+
|
|
111
|
+
Create a library entry that you will override dynamically.
|
|
112
|
+
|
|
113
|
+
```yaml
|
|
114
|
+
# my_theme.libraries.yml
|
|
115
|
+
versioned-assets:
|
|
116
|
+
js:
|
|
117
|
+
# This is just a placeholder. It will be replaced.
|
|
118
|
+
js/placeholder.js: {}
|
|
119
|
+
css:
|
|
120
|
+
# This is just a placeholder. It will be replaced.
|
|
121
|
+
theme:
|
|
122
|
+
css/placeholder.css: {}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
**B. Read the manifest and alter the library in `my_theme.theme`:**
|
|
126
|
+
|
|
127
|
+
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.
|
|
128
|
+
|
|
129
|
+
```php
|
|
130
|
+
<?php
|
|
131
|
+
// my_theme.theme
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Implements hook_page_attachments_alter().
|
|
135
|
+
*/
|
|
136
|
+
function my_theme_page_attachments_alter(array &$attachments) {
|
|
137
|
+
// 1. Decide which version to load.
|
|
138
|
+
// This is where your feature flagging logic goes. For example, you could use a query
|
|
139
|
+
// parameter, a config setting, or check the user's role.
|
|
140
|
+
// For this example, we'll just load the 'latest_version'.
|
|
141
|
+
$version_to_load = NULL;
|
|
142
|
+
|
|
143
|
+
// 2. Read and parse the manifest.json.
|
|
144
|
+
$manifest_path = \Drupal::service('extension.path.resolver')->getPath('theme', 'my_theme') . '/version-builder/build/manifest.json';
|
|
145
|
+
if (file_exists($manifest_path)) {
|
|
146
|
+
$manifest = json_decode(file_get_contents($manifest_path), TRUE);
|
|
147
|
+
|
|
148
|
+
// Get the version key from your logic.
|
|
149
|
+
$version_to_load = $manifest['latest_version']; // Or get from a feature flag service.
|
|
150
|
+
|
|
151
|
+
if (isset($manifest['versions'][$version_to_load])) {
|
|
152
|
+
$assets = $manifest['versions'][$version_to_load];
|
|
153
|
+
|
|
154
|
+
// 3. Dynamically override the library definition.
|
|
155
|
+
// The key 'my_theme/versioned-assets' matches the library defined in your .libraries.yml file.
|
|
156
|
+
$attachments['#attached']['library']['my_theme/versioned-assets'] = [
|
|
157
|
+
'js' => [
|
|
158
|
+
// The path is relative to your Drupal root.
|
|
159
|
+
'themes/custom/my_theme/version-builder/build' . $assets['main.js'] => [],
|
|
160
|
+
],
|
|
161
|
+
'css' => [
|
|
162
|
+
'theme' => [
|
|
163
|
+
'themes/custom/my_theme/version-builder/build' . $assets['style.css'] => [],
|
|
164
|
+
],
|
|
165
|
+
],
|
|
166
|
+
];
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
### 4. Attach the Library in Your Twig Templates
|
|
173
|
+
|
|
174
|
+
Finally, in your Drupal theme's Twig templates (e.g., `page.html.twig`), you attach the library as you normally would.
|
|
175
|
+
|
|
176
|
+
```twig
|
|
177
|
+
{# templates/page.html.twig #}
|
|
178
|
+
|
|
179
|
+
{{ attach_library('my_theme/versioned-assets') }}
|
|
180
|
+
|
|
181
|
+
<div class="page-content">
|
|
182
|
+
...
|
|
183
|
+
</div>
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Summary of the Workflow
|
|
75
187
|
|
|
76
|
-
|
|
188
|
+
1. You work on your assets inside the `version-builder/src` directory.
|
|
189
|
+
2. You run `npm run build` to create a new, versioned set of assets and update the `manifest.json`.
|
|
190
|
+
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.
|
|
191
|
+
4. Drupal attaches those specific, versioned files to the page.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
document.addEventListener("DOMContentLoaded",()=>{const e=document.getElementById("app");e.textContent="Hello from version-builder!"});
|
package/build/manifest.json
CHANGED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
: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)}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "feat-flag-drupal",
|
|
3
|
-
"version": "0.0
|
|
3
|
+
"version": "0.1.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"main": "build/main.js",
|
|
6
6
|
"files": [
|
|
@@ -15,5 +15,7 @@
|
|
|
15
15
|
"devDependencies": {
|
|
16
16
|
"sass-embedded": "^1.98.0",
|
|
17
17
|
"vite": "^7.0.0"
|
|
18
|
-
}
|
|
18
|
+
},
|
|
19
|
+
"license": "MIT",
|
|
20
|
+
"description": "A tool to build and manage versioned assets for Drupal themes, enabling feature flagging and A/B testing."
|
|
19
21
|
}
|