UNPKG

6.26 kBMarkdownView Raw
1# Installation
2
3## Trying out Marko
4
5If you just want to play around with Marko in the browser, head on over to our [Try Online](https://markojs.com/try-online) feature. You'll be able to develop a Marko application right in your browser.
6
7## Creating new apps
8
9If you're starting from scratch, [`marko-cli`](https://github.com/marko-js/cli) provides a starter app to
10get you going quickly. To get started:
11
12```bash
13npm install marko-cli --global
14marko create hello-world
15cd hello-world
16npm start
17```
18
19## Direct usage
20
21### Installing
22
23The Marko compiler runs on [Node.js](https://nodejs.org/) and can be installed using [npm](https://www.npmjs.com/package/marko):
24
25```
26npm install marko
27```
28
29or using [yarn](https://yarnpkg.com):
30
31```
32yarn add marko
33```
34
35### In the browser
36
37Let's say we have a simple view that we want to render in the browser: `hello.marko`
38
39_hello.marko_
40
41```marko
42<h1>Hello ${input.name}</h1>
43```
44
45First, let's create a `client.js` that requires the view and renders it to the body:
46
47_client.js_
48
49```js
50var helloComponent = require("./hello");
51
52helloComponent.renderSync({ name: "Marko" }).appendTo(document.body);
53```
54
55We will also create a barebones HTML page to host our application:
56
57_index.html_
58
59```
60<!doctype html>
61<html>
62<head>
63 <title>Marko Example</title>
64</head>
65<body>
66
67</body>
68</html>
69```
70
71Now, we need to bundle these files for use in the browser. We can use a tool called [`lasso`](https://github.com/lasso-js/lasso) to do that for us, so let's get it (and the marko plugin) installed:
72
73```
74npm install --global lasso-cli
75npm install --save lasso lasso-marko
76```
77
78Now we can build our bundle for the browser:
79
80```
81lasso --main client.js --plugins lasso-marko --inject-into index.html
82```
83
84This builds a `client.js` file to the newly created `static/` directory and injects the required `<script>` tags into our HTML page to load our application in the browser. If we had css in the view then `<link>` tags would have also been added.
85
86Load up that page in your browser and you should see `Hello Marko` staring back at you.
87
88### On the server
89
90#### Require Marko views
91
92Marko provides a custom Node.js require extension that allows you to `require` Marko views exactly like a standard JavaScript module. Take the following example `server.js`:
93
94_hello.marko_
95
96```marko
97<div>
98 Hello ${input.name}!
99</div>
100```
101
102_server.js_
103
104```js
105// The following line installs the Node.js require extension
106// for `.marko` files. This should be called once near the start
107// of your application before requiring any `*.marko` files.
108require("marko/node-require");
109
110var fs = require("fs");
111
112// Load a Marko view by requiring a .marko file:
113var hello = require("./hello");
114var out = fs.createWriteStream("hello.html", { encoding: "utf8" });
115hello.render({ name: "Frank" }, out);
116```
117
118Using the Node.js require extension is completely optional. If you prefer to not use the Node.js require extension then you will need to precompile all of the marko templates using [Marko CLI](https://github.com/marko-js/cli):
119
120```bash
121marko compile hello.marko
122```
123
124This will produce a `hello.marko.js` file next to the original template. The generated `.js` file will be what gets loaded by the Node.js runtime. It is important to leave off the `.marko` extension when requiring a Marko template so that the `.js` will be resolved correctly.
125
126If you wish to only use the require extension in development, you can conditionally require it.
127
128```js
129if (!process.env.NODE_ENV) {
130 require("marko/node-require");
131}
132```
133
134#### Serving a simple page
135
136Let's update `server.js` to serve the view from an http server:
137
138_server.js_
139
140```js
141// Allow requiring `.marko` files
142require("marko/node-require");
143
144var http = require("http");
145var hello = require("./hello");
146var port = 8080;
147
148http
149 .createServer((req, res) => {
150 // let the browser know html is coming
151 res.setHeader("content-type", "text/html");
152
153 // render the output to the `res` output stream
154 hello.render({ name: "Marko" }, res);
155 })
156 .listen(port);
157```
158
159And give `hello.marko` some content:
160
161_hello.marko_
162
163```marko
164<h1>Hello ${input.name}</h1>
165```
166
167Start the server (`node server.js`) and open your browser to [http://localhost:8080](http://localhost:8080) where you should see the heading `Hello Marko`.
168
169#### Initializing server-rendered components
170
171Marko automatically injects a list of components that need to be mounted in the browser, right before the closing `</body>` tag (as such, it required that you include a `<body>` in your rendered output).
172
173However, you still need to bundle the CSS & JavaScript for your page and include the proper `link`, `style`, and `script` tags. Luckily, the `lasso` taglib will do all the heavy lifting for you.
174
175First install `lasso` and `lasso-marko`:
176
177```
178npm install --save lasso lasso-marko @lasso/marko-taglib
179```
180
181Next, register and config the lasso:
182
183_server.js_
184
185```js
186var isProduction = process.env.NODE_ENV === "production";
187
188// Configure lasso to control how JS/CSS/etc. is delivered to the browser
189require("lasso").configure({
190 plugins: [
191 "lasso-marko" // Allow Marko templates to be compiled and transported to the browser
192 ],
193 outputDir: __dirname + "/static", // Place all generated JS/CSS/etc. files into the "static" dir
194 bundlingEnabled: isProduction, // Only enable bundling in production
195 minify: isProduction, // Only minify JS and CSS code in production
196 fingerprintsEnabled: isProduction // Only add fingerprints to URLs in production
197});
198```
199
200Next, in your page or layout view, add the `lasso-head` and `lasso-body` tags:
201
202_layout.marko_
203
204```marko
205<!doctype>
206<html>
207<head>
208 <title>Hello world</title>
209 <lasso-head/>
210</head>
211<body>
212 <${input.body}/>
213 <lasso-body/>
214</body>
215</html>
216```
217
218Finally, configure your server to serve the static files that `lasso` generates:
219
220If you're using `express`, just do:
221
222_server.js_
223
224```js
225app.use(require("lasso/middleware").serveStatic());
226```
227
228And if `koa`, do:
229
230_server.js_
231
232```js
233const mount = require("koa-mount");
234const serve = require("koa-static");
235
236app.use(mount("/static", serve(__dirname + "/static")));
237```
238
239For the full application code for the Koa and assets bundling, please see the sample: [Marko + Koa](https://github.com/marko-js-samples/marko-koa).