@kitsy/cnos-docs 1.5.0 → 1.5.1
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/docs/api/runtime.mdx
CHANGED
|
@@ -32,6 +32,8 @@ The runtime currently exposes:
|
|
|
32
32
|
- `cnos.toNamespace(namespace)`
|
|
33
33
|
- `cnos.toEnv()`
|
|
34
34
|
- `cnos.toPublicEnv()`
|
|
35
|
+
- `cnos.format(message)`
|
|
36
|
+
- `cnos.log(message)`
|
|
35
37
|
|
|
36
38
|
Example:
|
|
37
39
|
|
|
@@ -45,8 +47,13 @@ const dbPassword = cnos.secret('db.password');
|
|
|
45
47
|
const profile = cnos.meta('profile');
|
|
46
48
|
const port = cnos.readOr('value.server.port', 3000);
|
|
47
49
|
const flags = cnos.toNamespace('flags');
|
|
50
|
+
const line = cnos.format('Starting server at ${value.server.port}');
|
|
51
|
+
|
|
52
|
+
cnos.log('Starting server at ${value.server.port}');
|
|
48
53
|
```
|
|
49
54
|
|
|
55
|
+
`cnos.format(...)` and `cnos.log(...)` interpolate `${logical.key}` placeholders through the active runtime. Missing keys are left unchanged.
|
|
56
|
+
|
|
50
57
|
## Typed values
|
|
51
58
|
|
|
52
59
|
CNOS values are not limited to strings. If the underlying config stores numbers, booleans, arrays, or objects, runtime reads return those values as-is.
|
|
@@ -16,7 +16,7 @@ public:
|
|
|
16
16
|
- flags.upi_enabled
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
Use an async webpack config:
|
|
19
|
+
Use an async webpack config. If your repo already uses ESM webpack config, this is the cleanest shape:
|
|
20
20
|
|
|
21
21
|
```ts
|
|
22
22
|
import { createCnos } from '@kitsy/cnos/configure';
|
|
@@ -40,6 +40,38 @@ export default async () => {
|
|
|
40
40
|
};
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
+
If your project uses CommonJS-style webpack config, keep `module.exports = async () => ...` and load CNOS with dynamic `import()` inside the async factory:
|
|
44
|
+
|
|
45
|
+
```js
|
|
46
|
+
const ESLintPlugin = require('eslint-webpack-plugin');
|
|
47
|
+
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
|
|
48
|
+
const HtmlWebpackPlugin = require('html-webpack-plugin');
|
|
49
|
+
|
|
50
|
+
module.exports = async () => {
|
|
51
|
+
const { createCnos } = await import('@kitsy/cnos/configure');
|
|
52
|
+
const { CnosWebpackPlugin } = await import('@kitsy/cnos-webpack');
|
|
53
|
+
|
|
54
|
+
const profile = process.env.NODE_ENV === 'production' ? 'prod' : 'local';
|
|
55
|
+
const cnos = await createCnos({ profile });
|
|
56
|
+
|
|
57
|
+
return {
|
|
58
|
+
devServer: {
|
|
59
|
+
port: Number(cnos.readOr('value.devServer.port', 3000)),
|
|
60
|
+
},
|
|
61
|
+
plugins: [
|
|
62
|
+
new CnosWebpackPlugin({ profile }),
|
|
63
|
+
new HtmlWebpackPlugin({
|
|
64
|
+
templateParameters: {
|
|
65
|
+
appName: cnos.read('public.app.name'),
|
|
66
|
+
},
|
|
67
|
+
}),
|
|
68
|
+
new MiniCssExtractPlugin(),
|
|
69
|
+
new ESLintPlugin(),
|
|
70
|
+
],
|
|
71
|
+
};
|
|
72
|
+
};
|
|
73
|
+
```
|
|
74
|
+
|
|
43
75
|
Read in browser code:
|
|
44
76
|
|
|
45
77
|
```ts
|
|
@@ -54,5 +86,35 @@ The webpack plugin:
|
|
|
54
86
|
- injects `process.env.*` define replacements for promoted public values
|
|
55
87
|
- embeds `globalThis.__CNOS_BROWSER_DATA__` for `@kitsy/cnos/browser`
|
|
56
88
|
- keeps server-only `value.*` and `secret.*` out of the browser bundle
|
|
89
|
+
- uses no prefix by default for webpack public env unless you configure `public.frameworks.webpack` or pass `prefix`
|
|
57
90
|
|
|
58
91
|
If you need build-time server config such as `devServer.port`, read it in the webpack config through `createCnos()` so dev and production builds use the same CNOS source of truth.
|
|
92
|
+
|
|
93
|
+
## Plugin order
|
|
94
|
+
|
|
95
|
+
Recommended order:
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
plugins: [
|
|
99
|
+
new CnosWebpackPlugin({ profile }),
|
|
100
|
+
new HtmlWebpackPlugin(...),
|
|
101
|
+
new MiniCssExtractPlugin(...),
|
|
102
|
+
new CopyPlugin(...),
|
|
103
|
+
new ESLintPlugin(...),
|
|
104
|
+
]
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Guidance:
|
|
108
|
+
- Put `CnosWebpackPlugin` early in the plugin list.
|
|
109
|
+
- `HtmlWebpackPlugin`, `MiniCssExtractPlugin`, `CopyPlugin`, and `ESLintPlugin` can follow it.
|
|
110
|
+
- If you need CNOS values in HTML templates, read them with `createCnos()` in the webpack config and pass them through `templateParameters`. `DefinePlugin` replacements do not automatically populate HTML templates.
|
|
111
|
+
|
|
112
|
+
## Why `require is not defined` happens
|
|
113
|
+
|
|
114
|
+
If webpack-cli logs a path like `file:///.../webpack.config.js`, it loaded your config as ESM. In that mode, `require(...)` is not available.
|
|
115
|
+
|
|
116
|
+
Choose one style and stay consistent:
|
|
117
|
+
- ESM: `webpack.config.mjs` or a package with `"type": "module"` and `import ...`
|
|
118
|
+
- CommonJS: `webpack.config.cjs` or CommonJS `module.exports = async () => ...`, using dynamic `import()` for CNOS ESM packages
|
|
119
|
+
|
|
120
|
+
Do not mix top-level `await` plus `require(...)` in a config file that webpack treats as ESM.
|