1 | # vitreum
|
2 | An opinioned build system for modern web apps.
|
3 |
|
4 | [![npm version](https://badge.fury.io/js/vitreum.svg)](https://badge.fury.io/js/vitreum)
|
5 |
|
6 |
|
7 | `vitreum` is a build tool for creating web applications; similar to webpack and [parcel](https://parceljs.org/). It uses common tools: React, Browserify, LESS, and LiveReload. `vitreum` focuses on incredibly fast build times and tooling for tightly active development.
|
8 |
|
9 |
|
10 |
|
11 | ### How it works
|
12 |
|
13 | Vitreums goal is to take a webapp code, format it, and bundle it so it can be served and rendered client-side. Vitreum takes in a list of entrypoint files; For each file it walks down it's dependacies, [transforming](docs/transforms.md) the file and then adding it to the various bundles.
|
14 | It produces a `bundle.js`, `bundle.css`, and `render.js` for each entrypoint. And produces a shared `libs.js` and an `/assets` folder.
|
15 |
|
16 |
|
17 | #### Produced Files
|
18 |
|
19 | - `/build/[entrypoint]/bundle.js` is a complete client-side ready bundle of all the code needed to run that single entrypoint. On require it exposes the top level export of the entrypoint.
|
20 |
|
21 | - `/build/[entrypoint]/bundle.css` is a complete bundle of all the required in style files (`.css` or `.less`) needed for that entrypoint.
|
22 |
|
23 | - `/build/[entrypoint]/render.js` is used for doing easy isomorphic rendering. It exports a syncronous function that takes a `props` object and an option `opts` object as parameters. It returns a sever-side rendered HTML string of the bundle given those props passed in.
|
24 |
|
25 | Default options for `opts` are `{ render : true, cache : false }`. When `cache` is set to `true` the function will return a cached result if provided identical props it has seen before.
|
26 |
|
27 | *Note:* Vitreum will populate a global variable client-side called `vitreum_props` with a copy of the props passed in via the `render.js`. This is populated before any other code is loaded so it can be used immediately.
|
28 |
|
29 | ```js
|
30 | // Express Example
|
31 | const app = require('express')();
|
32 | const MainRender = require('./build/main/render.js');
|
33 |
|
34 | app.get('/', (req, res)=>{
|
35 | res.send(MainRender({ url : req.url });
|
36 | });
|
37 | ```
|
38 |
|
39 |
|
40 |
|
41 | - `/build/libs.js` is a bundling of all the libraries used by the entrpoints. As Vitreum is detecting dependacies, if a depedancy is located in the `node_modules` folder (and not defined in the `bundle` option), it's added to `libs.js`. This operation is expensive so dev-builds on Vitreum will not bundle libs.
|
42 |
|
43 | - `/build/assets/...` is a directory of all the copies of assets discovered during the build process. Each file path to the asset is the same as it is in the project.
|
44 |
|
45 |
|
46 | ## Key Concepts
|
47 |
|
48 |
|
49 | ### folder-based components
|
50 | One of the core reason why Vitreum exists to to make it easy to use folder-based components. These components are self-contained within a folder with a JSX component, an associated LESS file with it, and any files or sub-compoennts that it needs.
|
51 |
|
52 | This method keeps your components incredibly modular and then your file system reflects your component hierarchy.
|
53 |
|
54 | ```
|
55 | /page
|
56 | ├─ page.jsx
|
57 | ├─ page.less
|
58 | ├─ user.png
|
59 | └─ /widget
|
60 | ├─ widget.jsx
|
61 | └─ widget.less
|
62 | ```
|
63 |
|
64 | ### Isomorphic Rendering
|
65 | [Isomorphic Rendering](https://medium.com/airbnb-engineering/isomorphic-javascript-the-future-of-web-apps-10882b7a2ebc#.4nyzv6jea) is the process of pre-rendering what your site should look like on a per request basis, rendering it to an HTML string on the server and sending that back on request.
|
66 |
|
67 |
|
68 | ### Transforms
|
69 | Whenever Vitreum encounters a file it will check it's list of [transforms](docs/transforms.md) and potentially modify the file (or do other operations) before it adds it to the bundle. These transforms allow you to require in assets, styles, or other various files.
|
70 |
|
71 |
|
72 |
|
73 | ### Live-reloading
|
74 |
|
75 | When running a dev-build Vitreum will [livereload](http://livereload.com/) any code and style changes that happen. By installing and using the [LiveReload extension](https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei?hl=en) your browser will instantly switch up javscript and styles when they change.
|
76 |
|
77 |
|
78 |
|
79 | ## Additional Docs
|
80 |
|
81 | - [Command Line Tools](docs/cli.md)
|
82 | - [Options](docs/options.md)
|
83 | - [Headtags](docs/headtags.md)
|
84 | - [Requirable](docs/requirable.md)
|
85 | - [Transforms](docs/transforms.md)
|
86 | - [Migration from v4](docs/migration.md) |
\ | No newline at end of file |