Skip to content

Commit 470d37c

Browse files
ringodsJosefBredereckmfranzke
authored
Pattern Lab only loads the pattern engines from the config (#1256)
* PatternLab loads the pattern engines from the config first, before fallback to scanning node_modules * chore: wording and headline structure * chore: wording * docs: further clarification through logging * fix: configuration * docs: let's get rid of that old mustache engine * refactor: we should only include the outdated mustache engine interally, but not publicly facing any more * chore: adapted that entry from the other places * chore: let's not mention mustache any more * docs: wording * docs: added a link * chore: added relevant comment * Update patternlab-config.json * Restore packages/core/test/files/_handlebars-test-patterns/atoms/global/helloworld-withdata.hbs * Update advanced-config-options.md * Update pattern_engines.js * Update packages/docs/src/docs/advanced-config-options.md Co-authored-by: Josef Bredreck <slime.games@outlook.de> Co-authored-by: Maximilian Franzke <787658+mfranzke@users.noreply.github.com> Co-authored-by: Josef Bredreck <13408112+JosefBredereck@users.noreply.github.com>
1 parent c69c658 commit 470d37c

File tree

12 files changed

+194
-26
lines changed

12 files changed

+194
-26
lines changed

‎packages/cli/test/fixtures/patternlab-config.json

+11-1
Original file line numberDiff line numberDiff line change
@@ -83,5 +83,15 @@
8383
"color": "dark",
8484
"density": "compact",
8585
"layout": "horizontal"
86-
}
86+
},
87+
"engines": {
88+
"handlebars": {
89+
"package": "@pattern-lab/engine-handlebars",
90+
"fileExtensions": [
91+
"handlebars",
92+
"hbs"
93+
],
94+
"extend": "helpers/*.js"
95+
}
96+
}
8797
}

‎packages/core/patternlab-config.json

+10
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,16 @@
8888
"density": "compact",
8989
"layout": "horizontal"
9090
},
91+
"engines": {
92+
"handlebars": {
93+
"package": "@pattern-lab/engine-handlebars",
94+
"fileExtensions": [
95+
"handlebars",
96+
"hbs"
97+
],
98+
"extend": "helpers/*.js"
99+
}
100+
},
91101
"uikits": [
92102
{
93103
"name": "uikit-workshop",

‎packages/core/src/lib/pattern_engines.js

+91-24
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,19 @@ function findEngineModulesInDirectory(dir) {
6262
return foundEngines;
6363
}
6464

65+
function findEnginesInConfig(config) {
66+
if ('engines' in config) {
67+
return config.engines;
68+
}
69+
logger.warning(
70+
"Scanning the 'node_modules' folder for pattern engines is deprecated and will be removed in v6."
71+
);
72+
logger.warning(
73+
'To configure your engines in patternlab-config.json, see https://patternlab.io/docs/editing-the-configuration-options/#heading-engines'
74+
);
75+
return null;
76+
}
77+
6578
//
6679
// PatternEngines: the main export of this module
6780
//
@@ -86,52 +99,106 @@ const PatternEngines = Object.create({
8699
loadAllEngines: function (patternLabConfig) {
87100
const self = this;
88101

89-
// Try to load engines! We scan for engines at each path specified above. This
90-
// function is kind of a big deal.
91-
enginesDirectories.forEach(function (engineDirectory) {
92-
const enginesInThisDir = findEngineModulesInDirectory(
93-
engineDirectory.path
94-
);
102+
// Try to load engines! We load the engines configured in patternlab-config.json
103+
const enginesInConfig = findEnginesInConfig(patternLabConfig);
95104

96-
logger.debug(
97-
`Loading engines from ${engineDirectory.displayName}: ${engineDirectory.path} ...`
98-
);
105+
if (enginesInConfig) {
106+
// Quick fix until we've removed @pattern-lab/engine-mustache, starting with https://github.com/pattern-lab/patternlab-node/issues/1239 & https://github.com/pattern-lab/patternlab-node/pull/1455
107+
// @TODO: Remove after removing @pattern-lab/engine-mustache dependency
108+
enginesInConfig.mustache = enginesInConfig.mustache || {};
109+
enginesInConfig.mustache.package =
110+
enginesInConfig.mustache.package || '@pattern-lab/engine-mustache';
111+
enginesInConfig.mustache.extensions =
112+
enginesInConfig.mustache.extensions || 'mustache';
99113

100-
// find all engine-named things in this directory and try to load them,
101-
// unless it's already been loaded.
102-
enginesInThisDir.forEach(function (engineDiscovery) {
114+
// Try loading each of the configured pattern engines
115+
// eslint-disable-next-line guard-for-in
116+
for (const name in enginesInConfig) {
117+
const engineConfig = enginesInConfig[name];
103118
let errorMessage;
104119
const successMessage = 'good to go';
105120

106121
try {
107122
// Give it a try! load 'er up. But not if we already have,
108-
// of course. Also pass the pattern lab config object into
123+
// of course. Also pass the Pattern Lab config object into
109124
// the engine's closure scope so it can know things about
110125
// things.
111-
if (self[engineDiscovery.name]) {
126+
if (self[name]) {
112127
throw new Error('already loaded, skipping.');
113128
}
114-
self[engineDiscovery.name] = require(engineDiscovery.modulePath);
115-
if (
116-
typeof self[engineDiscovery.name].usePatternLabConfig === 'function'
117-
) {
118-
self[engineDiscovery.name].usePatternLabConfig(patternLabConfig);
119-
}
120-
if (typeof self[engineDiscovery.name].spawnMeta === 'function') {
121-
self[engineDiscovery.name].spawnMeta(patternLabConfig);
129+
if ('package' in engineConfig) {
130+
self[name] = require(engineConfig.package);
131+
if (typeof self[name].usePatternLabConfig === 'function') {
132+
self[name].usePatternLabConfig(patternLabConfig);
133+
}
134+
if (typeof self[name].spawnMeta === 'function') {
135+
self[name].spawnMeta(patternLabConfig);
136+
}
137+
} else {
138+
logger.warning(
139+
`Engine ${name} not configured correctly. Please configure your engines in patternlab-config.json as documented in https://patternlab.io/docs/editing-the-configuration-options/#heading-engines`
140+
);
122141
}
123142
} catch (err) {
124143
errorMessage = err.message;
125144
} finally {
126145
// report on the status of the engine, one way or another!
127146
logger.info(
128-
`Pattern Engine ${engineDiscovery.name}: ${
147+
`Pattern Engine ${name} / package ${engineConfig.package}: ${
129148
errorMessage ? errorMessage : successMessage
130149
}`
131150
);
132151
}
152+
}
153+
} else {
154+
// Try to load engines! We scan for engines at each path specified above. This
155+
// function is kind of a big deal.
156+
enginesDirectories.forEach(function (engineDirectory) {
157+
const enginesInThisDir = findEngineModulesInDirectory(
158+
engineDirectory.path
159+
);
160+
161+
`Loading engines from ${engineDirectory.displayName}: ${engineDirectory.path} ...`;
162+
163+
// find all engine-named things in this directory and try to load them,
164+
// unless it's already been loaded.
165+
enginesInThisDir.forEach(function (engineDiscovery) {
166+
let errorMessage;
167+
const successMessage = 'good to go';
168+
169+
try {
170+
// Give it a try! load 'er up. But not if we already have,
171+
// of course. Also pass the Pattern Lab config object into
172+
// the engine's closure scope so it can know things about
173+
// things.
174+
if (self[engineDiscovery.name]) {
175+
throw new Error('already loaded, skipping.');
176+
}
177+
self[engineDiscovery.name] = require(engineDiscovery.modulePath);
178+
if (
179+
typeof self[engineDiscovery.name].usePatternLabConfig ===
180+
'function'
181+
) {
182+
self[engineDiscovery.name].usePatternLabConfig(patternLabConfig);
183+
}
184+
if (typeof self[engineDiscovery.name].spawnMeta === 'function') {
185+
self[engineDiscovery.name].spawnMeta(patternLabConfig);
186+
}
187+
} catch (err) {
188+
errorMessage = err.message;
189+
} finally {
190+
// report on the status of the engine, one way or another!
191+
logger.info(
192+
`Pattern Engine ${
193+
engineDiscovery.name
194+
} by discovery (deprecated): ${
195+
errorMessage ? errorMessage : successMessage
196+
}`
197+
);
198+
}
199+
});
133200
});
134-
});
201+
}
135202

136203
// Complain if for some reason we haven't loaded any engines.
137204
if (Object.keys(self).length === 0) {

‎packages/core/test/util/patternlab-config.json

+10
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,16 @@
7373
"density": "compact",
7474
"layout": "horizontal"
7575
},
76+
"engines": {
77+
"handlebars": {
78+
"package": "@pattern-lab/engine-handlebars",
79+
"fileExtensions": [
80+
"handlebars",
81+
"hbs"
82+
],
83+
"extend": "helpers/*.js"
84+
}
85+
},
7686
"uikits": [
7787
{
7888
"name": "uikit-workshop",

‎packages/development-edition-engine-handlebars/patternlab-config.json

+5
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,11 @@
108108
],
109109
"engines": {
110110
"handlebars": {
111+
"package": "@pattern-lab/engine-handlebars",
112+
"fileExtensions": [
113+
"handlebars",
114+
"hbs"
115+
],
111116
"extend": "helpers/*.js"
112117
}
113118
},

‎packages/development-edition-engine-react/patternlab-config.json

+8
Original file line numberDiff line numberDiff line change
@@ -87,5 +87,13 @@
8787
"color": "dark",
8888
"density": "compact",
8989
"layout": "horizontal"
90+
},
91+
"engines": {
92+
"react": {
93+
"package": "@pattern-lab/engine-react",
94+
"fileExtensions": [
95+
"jsx"
96+
]
97+
}
9098
}
9199
}

‎packages/development-edition-engine-twig/patternlab-config.json

+4
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,10 @@
104104
],
105105
"engines": {
106106
"twig": {
107+
"package": "@pattern-lab/engine-twig",
108+
"fileExtensions": [
109+
"twig"
110+
],
107111
"namespaces": {
108112
"atoms": "source/_patterns/atoms/",
109113
"molecules": "source/_patterns/molecules/",

‎packages/docs/src/docs/advanced-config-options.md

+32-1
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,37 @@ Sets the panel name and language for the code tab on the styleguide. Since this
180180

181181
**default**: `mustache`
182182

183+
## engines
184+
185+
An engine is a wrapper around a templating library like Handlebars, Twig or others. An [engine package](docs/template-language-and-patternengines/)
186+
is the bridge between Pattern Lab and the standalone NPM package supporting the templating language.
187+
188+
`engines` accepts an map of Engine objects. The mandatory properties for each Pattern Lab engine are:
189+
190+
- `package`: the NodeJS package name. Add the package of the engine as a dependency in `package.json` before you configure it here.
191+
- `fileExtensions`: list of pattern file extensions which will be handled by this pattern engine.
192+
193+
Other engine specific configuration options can be added and will be passed to the pattern engine at loading time. See the NPM package documentation for the properties each pattern engine supports.
194+
195+
**default**:
196+
197+
```javascript
198+
"engines": {
199+
"handlebars": {
200+
"package": "@pattern-lab/engine-handlebars",
201+
"extensions": [
202+
"handlebars",
203+
"hbs"
204+
],
205+
"extend": "helpers/*.js"
206+
...
207+
}
208+
}
209+
```
210+
211+
Configuring the engines in the config file was introduced in v5.14. The fallback lookup mode by scanning the
212+
`node_modules` folder is **deprecated** and will be removed in Pattern Lab v7.
213+
183214
## patternStateCascade
184215

185216
See the [Pattern State Documentation](/docs/using-pattern-states/)
@@ -402,7 +433,7 @@ Important details:
402433
- the [default `paths.source` object paths](https://github.com/pattern-lab/patternlab-node/pull/840/commits/a4961bd5d696a05fb516cdd951163b0f918d5e19) within `patternlab-config.json` are now relative to the current UIKit. See the [structure of uikit-workshop](https://github.com/pattern-lab/patternlab-node/tree/master/packages/uikit-workshop) for more info
403434
- the [default `paths.public` object paths](https://github.com/pattern-lab/patternlab-node/pull/840/commits/812bab3659f504043e8b61b1dc1cdac71f248449) within `patternlab-config.json` are now relative to the current UIKit's `outputDir`. Absolute paths will no longer work. Someone could test putting an absolute path in a UIKit `outputDir` property and see what happens I suppose.
404435
- `dependencyGraph.json` has moved to the project root rather than `public/` as we should only retain one
405-
- The lookup of the uikit by `name` is deprecated and the user will be notified of it. If the `package` property isn't defined, there is a default fallback lookup strategy where the value of `name` is tried as:
436+
- The lookup of the uikit by `name` is **deprecated** and will be removed in v7. The user will be notified of it. If the `package` property isn't defined, there is a default fallback lookup strategy where the value of `name` is tried as:
406437
- `<name>`
407438
- `uikit-<name>`
408439
- `@pattern-lab/<name>`

‎packages/edition-node-gulp/patternlab-config.json

+10
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,16 @@
8787
"density": "compact",
8888
"layout": "horizontal"
8989
},
90+
"engines": {
91+
"handlebars": {
92+
"package": "@pattern-lab/engine-handlebars",
93+
"fileExtensions": [
94+
"handlebars",
95+
"hbs"
96+
],
97+
"extend": "helpers/*.js"
98+
}
99+
},
90100
"uikits": [
91101
{
92102
"name": "uikit-workshop",

‎packages/edition-node/patternlab-config.json

+5
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,11 @@
9999
],
100100
"engines": {
101101
"handlebars": {
102+
"package": "@pattern-lab/engine-handlebars",
103+
"fileExtensions": [
104+
"handlebars",
105+
"hbs"
106+
],
102107
"extend": "helpers/*.js"
103108
}
104109
}

‎packages/edition-twig/patternlab-config.json

+4
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
{
22
"engines": {
33
"twig": {
4+
"package": "@pattern-lab/engine-twig-php",
5+
"fileExtensions": [
6+
"twig"
7+
],
48
"namespaces": [
59
{
610
"id": "uikit",

‎packages/starterkit-twig-demo/patternlab-config.json

+4
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
{
22
"engines": {
33
"twig": {
4+
"package": "@pattern-lab/engine-twig-php",
5+
"fileExtensions": [
6+
"twig"
7+
],
48
"namespaces": [
59
{
610
"id": "atoms",

0 commit comments

Comments
 (0)