|
18 | 18 |
|
19 | 19 | <hr> |
20 | 20 |
|
| 21 | +## Install[^type-module] |
| 22 | + |
| 23 | +```bash |
| 24 | +pnpm add kolay @universal-ember/kolay-ui |
| 25 | +``` |
| 26 | + |
| 27 | +[^type-module]: `@universal-ember/kolay-ui` is only needed because due to a temporary technical problem. Once the ember ecosystem has broader `package.json#type=module` support for its own ember using libraries, `@universal-ember/kolay-ui` can be removed and there will only be `kolay`. Note that `package.json#type=module` support is already working and has worked for a good number of years for non-Ember libraries. |
| 28 | + |
21 | 29 | ## Setup |
22 | 30 |
|
23 | | -There are two areas of configuration needed: buildtime, and runtime. |
| 31 | +There are two areas of configuration needed: buildtime, and runtime[^runtime-optional]. |
| 32 | + |
| 33 | +[^runtime-optional]: The runtime components are optional and if you don't import them, they will not be included in your app. However, since links generated from markdown use vanilla `<a>` tags, you'll probably want at least `@properLinks` from `ember-primitives`. |
24 | 34 |
|
25 | 35 | ### Build: Embroider + Webpack |
26 | 36 |
|
27 | 37 | import `kolay/webpack` |
28 | 38 |
|
29 | 39 | ```js |
30 | | -const { createManifest, apiDocs } = await import("kolay/webpack"); |
| 40 | +const { kolay } = await import("kolay/webpack"); |
31 | 41 |
|
32 | 42 | return require("@embroider/compat").compatBuild(app, Webpack, { |
33 | 43 | /* ... */ |
34 | 44 | packagerOptions: { |
35 | 45 | webpackConfig: { |
36 | 46 | devtool: "source-map", |
37 | | - plugins: [createManifest({ src: "public/docs" }), apiDocs({ package: "kolay" })], |
| 47 | + plugins: [ |
| 48 | + kolay({ |
| 49 | + src: "public/docs", |
| 50 | + // Generate API docs from JSDoc |
| 51 | + packages: ["kolay"], |
| 52 | + }), |
| 53 | + ], |
38 | 54 | }, |
39 | 55 | }, |
40 | 56 | }); |
41 | 57 | ``` |
42 | 58 |
|
43 | | -You can create docs for multiple libraries by invoking these plugins more than once: |
| 59 | +You can create docs for multiple libraries at once: |
44 | 60 |
|
45 | 61 | ```js |
46 | 62 | devtool: 'source-map', |
47 | 63 | plugins: [ |
48 | | - createManifest({ src: 'public/docs', name: 'own-manifest.json' }), |
49 | | - apiDocs({ package: 'kolay' }), |
50 | | - createManifest({ src: '../../my-library', name: 'my-library-manifest.json' }), |
51 | | - apiDocs({ package: 'my-library' }), |
| 64 | + kolay({ |
| 65 | + src: 'public/docs', |
| 66 | + groups: [ |
| 67 | + { |
| 68 | + name: 'Runtime', |
| 69 | + src: '../ui/docs', |
| 70 | + }, |
| 71 | + ], |
| 72 | + // Generate API docs from JSDoc |
| 73 | + // NOTE: these must all be declared in your projects package.json |
| 74 | + packages: ['kolay', 'ember-primitives', 'ember-resources'], |
| 75 | + }), |
52 | 76 | ], |
53 | 77 | ``` |
54 | 78 |
|
55 | | -See related for |
| 79 | +This is useful for monorepos where they may be scaling to large teams and many packages could end up being added quickly. In a traditionally compiled app, this may cause build times to slow down over time. Since many docs' sites are deployed continuously, that is wasted time and money spent on building things that may not be looked at all that often (we all wish folks looked at docs more!). |
56 | 80 |
|
57 | | -- [createManifest(...)](/plugins/create-manifest.md) |
58 | | -- [apiDocs(...)](/plugins/api-docs.md) |
59 | | -- [All Build Plugins](/plugins/index.md) |
| 81 | +By distributing the rendering of pages to the browesr, we only pay for "build" when somenoe views the page. |
60 | 82 |
|
61 | 83 | ### Runtime: Routing |
62 | 84 |
|
|
0 commit comments