nano_spa v3.0.1
nano_spa
nano_spa is a way to write single page applications with lazy loading "features" aka "handlers" by default and auto generates docs for you.
NOTE: although most of the api is stable (render, to_dom), nano_spa
is still very experimental and changes might happend to the default handlers
Box, State, etc...
.
- Get Started
- CLI Usage
- render
- to_dom
- handlers - Box - State - Reducer - Router - Router::link - Router::head
- Create Your Own Handlers
- Generate Docs
- Deploy
Get started
- Create your apps directory (you can have many apps under one directory sharing the same features).
$
mkdir my-app && cd my-app
- initialize project
$
npm init -y && npm i nano_spa
- add start script in
package.json
{
"name": "my-app",
"version": "1.0.0",
"scripts": {
"start": "nano_spa start",
"build": "nano_spa build",
"docs": "nano_spa docs"
}
}
CLI usage
start
Starts the development server.
Arguments
-s
source folder to start the development server from, defaults toapp
.-p
port to serve, defaults to3000
.
Example:
the following starts the development server on another-app
directory on port 5000.
"scripts": {
"start:another-app": "nano_spa start -s another-app -p 5000"
}
$ npm run start:another-app
Requirements
inside the root of your "source" directory it must contains.
index.html
main.js
static
NOTE: if the above does not exist nano_spa will create a simple hello world starter for you.
build
Builds your project in dist-app
Arguments
-s
source folder to build, defaults toapp
.
Example:
the following builds another-app
to dist-another-app
{
"scripts": {
"build:another-app": "nano_spa build -s another-app"
}
}
$ npm build:another-app
Requirements
given the previous example you must have a another-app
directory.
docs
Generates documentation for the whole project, specifically from handlers-props
.
check handlers-props for more info.
render
render under the hood uses htm, this means that render just renders a string to jsx object.
simple usage
import render from 'nano_spa/render'
function app() {
return render`<div>Hello, world!</div>`
}
with components
import render from 'nano_spa/render'
// simple component.
function myComponent({msg}) {
return render`<div>${msg}</div>`
}
// also supports fragments.
function myFragment() {
return render`
<>
<li>1</li>
<li>2</li>
<li>3</li>
</>
`
}
function app() {
return render`
<div>
<${myComponent} msg='hello, world!' />
<${myFragment} />
</div>
`
}
to_dom
converts jsx made from render
to DOM nodes
usage
import render from 'nano_spa/render'
import to_dom from 'nano_spa/to_dom'
function app() {
return render`<div>Hello, world!</div>`
}
document.getElementById('root').appendChild(to_dom(render`<${app} />`))
in the case of app
returning a fragment, to_dom will return an array of DOM nodes.
function app() {
return render`
<>
<li>1</li>
<li>2</li>
</>
`
}
const appRoot = document.getElementById('root')
to_dom(render`<${app} />`).forEach(domNode => appRoot.appendChild(domNode))
handlers
Now that you are familiar with the core concepts of nano_spa
it is time to get familiar with handlers.
when using render
, the moment render
encounters an element that starts with an uppercase element E.g. <Div />
it will look for ./handlers/Div.js
and it will lazley load that module, without importing the module!
nano_spa
ships with default handlers:
- Box
- State
- Reducer
- Router
- Router::link
- Router::head
Box
Box is a very simple handler that transforms props to style elements.
prop | type | required | default | description |
---|---|---|---|---|
type | string | false | div | sets the DOM node type |
grid | boolean | false | none | sets the display to grid |
flex | boolean | false | none | sets the display to flex |
* | string | false | none | appends to the style attribute |
usage
import render from 'nano_spa/render'
function app() {
return render`
<Box
type='main'
padding='1rem'
background-color='blue'
display='grid'
>
Hello, world
</Box>
`
}
/*
*** note that we didn't import Box from 'somewhere' ***
this is the same as:
<main style='padding: 1rem; background-color: blue; display: grid;'>
Hello, world
</main>
*/
State
prop | type | required | default | description |
---|---|---|---|---|
state | object | true | none | none |
render | function | true | none | a function that takes state and setState as arguments and returns a component |
usage
import render from 'nano_spa/render'
// simple counter example.
const counter = (state, setState) => {
/*
setState only accepts function as argument and expected to
return an object.
*/
const increment = () => setState(oldState => ({
count: oldState.count + 1
}))
return render`
<div>
<button onclick=${increment}>
increment
</button>
${state.count}
</div>
`
}
function myComponent() {
const state = { count: 0 }
return render`<State state=${state} render=${counter} />`
}
Reducer
prop | type | required | default | description |
---|---|---|---|---|
initial | object | true | none | initial state |
reducer | function | true | none | a function that takes state, action as arguments and returns new state |
render | function | true | none | a function that takes state and dispatch as arguments and returns a component |
usage
import render from 'nano_spa/render'
const reducer = (state, action) => {
if(action.type == 'INCREMENT') {
return {...state, count: state.count + 1}
} else if(action.type == 'DECREMENT') {
return {...state, count: state.count - 1}
} else {
return state
}
}
const counter = (state, dispatch) => {
const increment = () => dispatch({type: 'INCREMENT'})
const decrement = () => dispatch({type: 'DECREMENT'})
return render`
<div>
<button onclick=${increment}>increment</button>
<button onclick=${decrement}>increment</button>
${state.count}
</div>
`
}
function myComponent() {
return render`
<Reducer
initial=${{ count: 0}}
reducer=${reducer}
render=${counter}
/>
`
}
Router
prop | type | required | default | description |
---|---|---|---|---|
dir | function | true | none | a function that returns a dynamic import statement |
on_mount | function | true | none | a function that takes DOM node of current page, and current route |
on_unmount | function | true | none | a function that takes DOM node of previous page, and previous route |
usage
// in main.js
import render from 'nano_spa/render'
function app() {
return render`
<div>
<h1>I will exist on every route!</h1>
<Router
dir=${page => import(`./pages/${page}.js`)}
on_mount=${console.log}
on_unmount=${console.log}
/>
</div>
`
}
/*
* now you have to create a directory `pages`
* inside `pages`:
* '/' maps to index.js
* 'a not found route' maps to 404.js
* or the default 404 page that comes with Router
*/
// in ./pages/index.js
import render from 'nano_spa/render'
export default () => render`<div>hello, world</div>`
Router@link
prop | type | required | default | description |
---|---|---|---|---|
href | string | true | none | none |
usage
/*
* Router::link supports any element that accepts an `onclick` method.
* a, button, img, ...etc. and will set `tabIndex` to 0. for a11y
* it's very important that you don not set href on the anchor tag here.
*/
// ...
`<Router::link href='/'>
<a>Home</a>
<//>`
// ...
Router@head
does not take any props just one or more children, and works on route level.
usage
// ...
`<Router::head>
<title>my-app | Home</title>
<meta name='description' content='this is our home page.'/>
<//>`
// ...
Create Your Own Handlers
handlers let you use your favorite data structures and the full capability of the web platform.
this means the possiblities are endless, you could make a react
handler if you want.
handlers accepts virtual node
(jsx object), utils
, and if it returns a DOM node then it will be appended to the rest of the jsx tree it does not return anything, then it will just execute whatever is inside of your handler, treating it as a side effect if you will.
utils
contains {to_dom, on}
in the root of your project create Hello.js
inside ./handlers
// inside ./handlers/Hello.js
export default helloHandler(vNode) {
const Hello = document.createElement('div')
Hello.innerText = 'hello, ' + vNode.props.name || ''
return Hello
}
usage
// inside ./app/main.js
import render from 'nano_spa/render'
import to_dom from 'nano_spa/to_dom'
function app() {
return render`
<Hello name='world'/>
`
}
document.getElementById('root').appendChild(to_dom(render`<${app} />`))
Generate Docs
To generate docs for your project nano_spa
looks for ./handlers-props/MyHandler.js
this will allow for development warnings + auto generated docs.
given the previous example Hello.js
to include it and the docs and have development environment warnings and errors you must create ./handlers-props/Hello.js
and populate it as follows.
// inside ./handlers-props/Hello.js
module.exports = {
name: {
type: ['string'],
required: false
}
}
NOTE: when you use the command nano_spa docs
inside scripts
in your package.json
nano_spa
will look at your handlers directory and generate empty prop-types for the handlers it found.
Deploy
the only thing to keep in mind when deploying is you serve index.html
at every route.
great deployment services like zeit/now
or netlify
provide a very easy way to do this.
that's it. examples coming soon!
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago