UNPKG

6.38 kBMarkdownView Raw
1# Marko + Lasso
2
3The [lasso-marko](https://github.com/lasso-js/lasso-marko) plugin for [Lasso.js](https://github.com/lasso-js/lasso) will automatically compile all imported Marko templates during bundling. In addition, the `lasso-marko` plugin will automatically bundle any template dependencies (including required CSS).
4
5Lasso.js provides Marko custom tags for injecting JavaScript and CSS bundles, images and other resources.
6
7The sample [marko-lasso](https://github.com/marko-js-samples/marko-lasso) app demonstrates how to build a production-ready web application using Marko and Lasso.
8
9## Installation
10
11```
12npm install lasso-marko --save
13```
14
15## Registering the plugin
16
17```js
18require('lasso').configure({
19 "plugins": [
20 ...
21 "lasso-marko"
22 ]
23 ...
24});
25```
26
27## Lasso custom tags
28
29To inject the required JavaScript and CSS into the page you will want to use the `<lasso-page>`, `<lasso-head>` and `<lasso-body>` tags.
30
31If you are using lasso@^3 (latest), make sure to install the [lasso-marko-taglib](https://github.com/lasso-js/lasso-marko-taglib), so that you can use the lasso custom tags.
32
33```
34npm install lasso-marko
35npm install @lasso/marko-taglib
36```
37
38After installing, the lasso custom tags can be used in your templates:
39
40```html
41<!DOCTYPE html>
42<html lang="en">
43 <head>
44 <meta charset="UTF-8" />
45 <title>Marko + Lasso</title>
46 <lasso-head />
47 </head>
48 <body>
49 <lasso-body />
50 </body>
51</html>
52```
53
54Lasso.js will automatically bundle up transitive dependencies by building and walking a dependency graph.
55
56## Client-side rendering
57
58Marko templates can be imported and rendered by any JavaScript module. The code below shows how to render a top-level UI component and have it be mounted to the DOM as a child `document.body`:
59
60_client.js_
61
62```js
63require("./components/app/index.marko")
64 .renderSync({})
65 .appendTo(document.body);
66```
67
68When Lasso.js bundles up the code above it will automatically bundle up the required `./components/app/index.marko` file.
69
70## Server-side rendering
71
72If you are rendering the initial UI on the server then it is necessary to make sure that all UI components are bundled and sent to the browser so that UI components can be mounted in the browser. For example:
73
74_about-me/index.marko_
75
76```marko
77<!DOCTYPE html>
78<html lang="en">
79 <head>
80 <meta charset="UTF-8">
81 <title>Marko + Lasso</title>
82
83 <!-- CSS will be inserted here -->
84 <lasso-head/>
85 </head>
86 <body>
87 <!-- Top-level UI component: -->
88 <app/>
89
90 <!-- JS will be inserted here -->
91 <lasso-body/>
92 </body>
93</html>
94```
95
96## Browser refresh
97
98[browser-refresh](https://github.com/patrick-steele-idem/browser-refresh) is recommended in development for instant page refreshes and hot reloading of Marko templates, styles and other resources. `browser-refresh` works well with Lasso and Marko and is very easy to use as a drop-in replacement for `node`:
99
100```bash
101browser-refresh server.js
102```
103
104## Lasso package types commonly used with Marko
105
106For many use cases, the combination of `lasso-marko` and `@lasso/marko-taglib` is sufficient to render and bundle components without the need for explicit `browser.json` files. For more advanced use cases, the following bundle types may be defined in a `browser.json` for Lasso.
107
108#### `marko-dependencies` _(provided by `lasso-marko`)_
109
110Includes all the dependencies needed by template and the code to register all components that would be rendered by the template. It does not automatically initialize the component, so is most useful if you need to initialize components manually.
111
112```json
113{
114 "type": "marko-dependencies",
115 "path": "src/ui-modules/outdated-browser-banner/index.marko"
116}
117```
118
119**Note:** To initialize the server rendered components, there are 2 steps:
120
121**Step 1:** Manually _retrieve_ server rendered components, shipped via `marko-dependencies`.
122
123To retrieve the list of server rendered components, do:
124
125```javascript
126template.render(data, (err, output) => {
127 const renderedComponentsList = require("marko/components").getRenderedComponents(
128 output.out
129 );
130 const html = output.getOutput();
131});
132res.json({
133 renderedComponentsList,
134 html
135});
136```
137
138**Step 2:** Manually _initialize_ server rendered components, shipped via `marko-dependencies`.
139
140To initialize the list of server rendered components, do:
141
142```javascript
143// from the response received, retrieve as
144require("marko/components").init(response.renderedComponentsList);
145```
146
147**Note:** Ensure Step 2 is inside a DOM-ready wrapper, for the legacy widgets layer to load (if there are widgets built out of Marko 3, that is being used inside a Marko 4 component.)
148
149#### `marko-hydrate` _(provided by `lasso-marko`)_
150
151Includes all the dependencies needed by template and the code to register all components that would be rendered by the template. This also includes the code to initialize the rendered components. Including this bundle on the page will automatically hydrate server rendered components.
152
153```json
154{
155 "type": "marko-hydrate",
156 "path": "src/ui-modules/outdated-browser-banner/index.marko"
157}
158```
159
160**Note:** `marko-hydrate` will initialize the component if its defined on the global `window.$components` which is inserted by `Marko` when it sees a `<body>` tag. Else, if you are just rendering out and lasso-ing the a portion of a page with a set of components, include `<init-components/>` at the end of the associated `template.marko` file that builds out the page fragment.
161
162#### `package`
163
164A collection of dependencies. `browser.json` is the most common package type.
165It could be used to point to another `browser.json` from within one component's `browser.json`.
166Typically also used when the dependencies of the referred `browser.json` have to be packaged inline.
167
168```json
169{
170 "type": "package",
171 "path": "src/ui-modules/show-diag/browser.json"
172}
173```
174
175#### `require`
176
177If a javascript file has to be wrapped over for its common JS syntax, to a browser understandable format.
178
179```json
180{
181 "type": "require",
182 "path": "src/ui-modules/dynamic-module-loader/dynamic-init-client.js"
183}
184```
185
186#### `require` and `run`
187
188If a javascript file has to be wrapped over for its common JS syntax, to a browser understandable format and be executed immediately.
189
190```json
191{
192 "run": true,
193 "type": "require",
194 "path": "src/ui-modules/my-module/init.js"
195}
196```