Napoleonic Political Magnificence

npm

Don't miss out on this year's npm Pride t-shirt designs!Order your favorites here »

upapp

0.19.2 • Public • Published

upapp

Greenkeeper badge

license npm Build Status Build status Coverage Status dependencies Status devDependencies Status Commitizen friendly Standard Version

A static site generator utilizing reactjs.

upapp generates html and copies your static resources into a give folder structure. Aftewards the generated html is validated for consistency.

Installation

npm install upapp

Quickstart

Create the following folder structure:

src
src/pages     <-- place your content here
src/templates <-- place your page components here
src/statics   <-- place all static assets here
src/helpers   <-- place all helper functions here (optional)
./node_modules/.bin/upapp

The result is written into the dist folder.

Usage

$ upapp
 
Usage
  $ upapp [options]
 
Options
 
  --help, -h             Usage information
  --src                  Source folder (defaults to src)
  --src-pages            Folder to look for pages (default to <src>/pages)
  --src-templates        Folder to look for templates (defaults to <src>/templates)
  --src-statics          Folder to look for static files (defaults to <src>/statics). Repeat for mulitple sources.
  --src-helpers          Folder to look for helper functions (defaults to <src>/helpers)
  --dest                 Destination folder (defaults to dist)
  --dest-statics         Folder to write statics (defaults to <dest>/statics)
  --var.<name>=<value>   Define global properties which are usable during build pages
  --disable-validation   Disable html validation (no link and resource checking)
  --redirect-map         A json file with key value pairs of url-path (source) and full qualifed urls (target)
  --scoped-css           Path of the file to write all scoped css to
  --css-variables        Enable support for css-variables
  --template-import='<file-or-node-module-path>[:<namespace>]'
                         Imports the react-components from the given path at the given namespace
 
Examples
  $ upapp # Execute with default 
  $ upapp --src-statics=./statics-one --src-statics=./statics-two

Pages

Pages in upapp are JSX files (only the JSX code without JavaScript boilerplate). All pages are stateless function components which could have a frontmatter preamble. The frontmatter could contain a route entry to specify the URL of the page to create. All other frontmatter data is given to the page under the scope frontmatter.

---
route: /index.html
text: Content!
---
<p>{frontmatter.text}</p>

Templates

Templates for upapp are either JSX files (only the JSX code without JavaScript boilerplate), SVG files or Markdown files. All templates are stateless function components which could have as well a frontmatter preamble.

The component name is either given in frontmatter as name or derived from the file name.

For example in a file named src/templates/my-component.html:

---
name: MyComponent
---
<div>
    {props.message || 'Lorem ipsum'}
</div>

This template (component) could then be used in a page with the name MyComponent.

For example in a file named src/pages/index.html:

<MyComponent message="Hello World!" />

Helpers

Helpers are functions which could be used in all templates.

Helpers must export a function at module.exports, the name of the helper is deduced from the camel-cased file name of the helper function.

For example in a file named src/helpers/hello-world.js:

module.exports = function () { return 'Hello World!'; };

This results in a helper which could be called in a template like this:

<div>
    {helpers.helloWorld()}
</div>

Note: The helpers are only availalbe in templates, NOT in pages.

Globals

Global variables which are available in all pages. These values are available as top-level props.

If upapp is executed with upapp --var.foo=bar and the following page:

<div>
    {props.foo}
</div>

this html is rendered as result: <div>bar</div>.

Validation

Currently the following elements get validated:

  • a[href] - relative links to pages must exist (no dead links)
  • img[src] - relatie image resources must exist
  • img[srcset] - relatie image resources must exist
  • *[style] background-image - relative resources in inline-style background-images must exist
  • link[href] - relative external resources must exist

Redirects

Given upapp is started with the parameter --redirect-map map.json and map.json contains:

{
  "/old/page/url": "https://github.com/sjoerdapp/upapp"
}

then upapp generates a page at <dest>/old/page/url/index.html which contains a meta refresh to https://github.com/sjoerdapp/upapp.

Scoped CSS

Pages and Templates could have a scoped css tag which contains the styles of that component. Only simple selectors are possible which implicitly means that the style rules are scoped to that component.

For ease of use and to keep templates dry and reusable css-variables have been implemented. That includes full support for inheritance/scoping. (Note: There is no interoperability between javascript and css. This means it is not possible to dynamically set variables.)

---
name: Element
---
<style scoped>
.element {
    color: blue;
    background-color: var(--common-background-color);
}
.element h1 {
    color: green;
}
h1 + p {
    color: red;
}
</style> 
<div className={style.element}>
    <h1>headline<h1>
    <p>
        copytext
    </p>
</div>

Template Imports

With the option --template-import it is possible to integrate external React libraries (e.g. elemental ui) into upapp sites.

The libraries are either referenced from node_modules (e.g. elemental) or by relative path (e.g. ./node_modules/elemental) and could be imported into an optional given namespace.

# This would import elemental-ui into the namespace UI 
$ upapp --template-import='elemental:UI'

Afterwards all components of the library could be used with the given namespace.

<body>
    <UI.Button/>
</body>

The option could occurr multiple times on the cli. If there are name clashes in the namespace and module names, the last given option overwrites former imports.

If there is no namespace given, then the library is imported into the default upapp template space. But it is not possible to overwrite local upapp templates by an imported library.


upapp is built with JavaScript and ❤️ and released under the MIT license.

install

npm i upapp

Downloadsweekly downloads

12

version

0.19.2

license

MIT

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability