1 | # Installation
|
2 |
|
3 | ## Trying out Marko
|
4 |
|
5 | If 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 |
|
9 | If you're starting from scratch, [`marko-cli`](https://github.com/marko-js/cli) provides a starter app to
|
10 | get you going quickly. To get started:
|
11 |
|
12 | ```bash
|
13 | npm install marko-cli --global
|
14 | marko create hello-world
|
15 | cd hello-world
|
16 | npm start
|
17 | ```
|
18 |
|
19 | ## Direct usage
|
20 |
|
21 | ### Installing
|
22 |
|
23 | The Marko compiler runs on [Node.js](https://nodejs.org/) and can be installed using [npm](https://www.npmjs.com/package/marko):
|
24 |
|
25 | ```
|
26 | npm install marko
|
27 | ```
|
28 |
|
29 | or using [yarn](https://yarnpkg.com):
|
30 |
|
31 | ```
|
32 | yarn add marko
|
33 | ```
|
34 |
|
35 | ### In the browser
|
36 |
|
37 | Let'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 |
|
45 | First, let's create a `client.js` that requires the view and renders it to the body:
|
46 |
|
47 | _client.js_
|
48 |
|
49 | ```js
|
50 | var helloComponent = require("./hello");
|
51 |
|
52 | helloComponent.renderSync({ name: "Marko" }).appendTo(document.body);
|
53 | ```
|
54 |
|
55 | We 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 |
|
71 | Now, 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 | ```
|
74 | npm install --global lasso-cli
|
75 | npm install --save lasso lasso-marko
|
76 | ```
|
77 |
|
78 | Now we can build our bundle for the browser:
|
79 |
|
80 | ```
|
81 | lasso --main client.js --plugins lasso-marko --inject-into index.html
|
82 | ```
|
83 |
|
84 | This 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 |
|
86 | Load 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 |
|
92 | Marko 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.
|
108 | require("marko/node-require");
|
109 |
|
110 | var fs = require("fs");
|
111 |
|
112 | // Load a Marko view by requiring a .marko file:
|
113 | var hello = require("./hello");
|
114 | var out = fs.createWriteStream("hello.html", { encoding: "utf8" });
|
115 | hello.render({ name: "Frank" }, out);
|
116 | ```
|
117 |
|
118 | Using 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
|
121 | marko compile hello.marko
|
122 | ```
|
123 |
|
124 | This 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 |
|
126 | If you wish to only use the require extension in development, you can conditionally require it.
|
127 |
|
128 | ```js
|
129 | if (!process.env.NODE_ENV) {
|
130 | require("marko/node-require");
|
131 | }
|
132 | ```
|
133 |
|
134 | #### Serving a simple page
|
135 |
|
136 | Let's update `server.js` to serve the view from an http server:
|
137 |
|
138 | _server.js_
|
139 |
|
140 | ```js
|
141 | // Allow requiring `.marko` files
|
142 | require("marko/node-require");
|
143 |
|
144 | var http = require("http");
|
145 | var hello = require("./hello");
|
146 | var port = 8080;
|
147 |
|
148 | http
|
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 |
|
159 | And give `hello.marko` some content:
|
160 |
|
161 | _hello.marko_
|
162 |
|
163 | ```marko
|
164 | <h1>Hello ${input.name}</h1>
|
165 | ```
|
166 |
|
167 | Start 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 |
|
171 | Marko 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 |
|
173 | However, 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 |
|
175 | First install `lasso` and `lasso-marko`:
|
176 |
|
177 | ```
|
178 | npm install --save lasso lasso-marko @lasso/marko-taglib
|
179 | ```
|
180 |
|
181 | Next, register and config the lasso:
|
182 |
|
183 | _server.js_
|
184 |
|
185 | ```js
|
186 | var isProduction = process.env.NODE_ENV === "production";
|
187 |
|
188 | // Configure lasso to control how JS/CSS/etc. is delivered to the browser
|
189 | require("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 |
|
200 | Next, 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 |
|
218 | Finally, configure your server to serve the static files that `lasso` generates:
|
219 |
|
220 | If you're using `express`, just do:
|
221 |
|
222 | _server.js_
|
223 |
|
224 | ```js
|
225 | app.use(require("lasso/middleware").serveStatic());
|
226 | ```
|
227 |
|
228 | And if `koa`, do:
|
229 |
|
230 | _server.js_
|
231 |
|
232 | ```js
|
233 | const mount = require("koa-mount");
|
234 | const serve = require("koa-static");
|
235 |
|
236 | app.use(mount("/static", serve(__dirname + "/static")));
|
237 | ```
|
238 |
|
239 | For the full application code for the Koa and assets bundling, please see the sample: [Marko + Koa](https://github.com/marko-js-samples/marko-koa).
|