Node.js

This documentation covers the usage of the Node server library for adding Shard support to your Node.js server. See the GitHub project to component the code, submit pull requests, and open issues.

The library and docs use TypeScript but of course it also supports using the it with plain JavaScript. Throughout these docs we will assume you are using jsx but you can also use Shard without jsx, see Without JSX.

Installation

Simply add the library to you project.

Using npm:

> npm install --save @visly/shard-node-server

Using yarn:

> yarn add @visly/shard-node-server

JSX

TypeScript

To start using Shard + JSX with TypeScript you have to modify your .tsconfig and add the following configuration

{
"compilerOptions": {
"jsx": "react",
"jsxFactory": "Shard.createElement",
},
}

Now all that is needed is to make sure to import the library as Shard in your TypeScript files.

import Shard from '@visly/shard-node-server'

Babel

To start using Shard with a JavaScript + Babel setup you should first make sure you install the jsx babel transform.

Using npm:

> npm install --save-dev @babel/plugin-transform-react-jsx

Using yarn:

yarn add --dev @babel/plugin-transform-react-jsx

Once the babel transform is installed you will need to add it to your .babelrc and configure it to use the Shard transform instead of the standard react transform.

{
"plugins": [
["@babel/plugin-transform-react-jsx", {
"pragma": "Shard.createElement",
}]
]
}

Lastly, make sure to import the library as Shard in your JavaScript files.

import Shard from '@visly/shard-node-server'

Without JSX

Shard can be used without jsx as well. For example, the following jsx code

import Shard from '@visly/shard-node-server'
<flexbox flexDirection="row">
<image src="./image.png"/>
<MyComponent/>
</flexbox>

in equivalent to

import Shard from '@visly/shard-node-server'
const shard = Shard.createElement;
shard('flexbox', {
flexDirection: 'row'
},
shard('image', {src: './image.png'}),
shard(MyComponent, {})
)

Getting started

Hello world

For this guide we will be using express but any web framework will be compatible as long as it allows you to return JSON responses.

Let's start by creating a new project and adding the needed dependencies.

> mkdir shard-test
> cd shard-test
> npm init -y
> npm install --save @visly/shard-node-server express

At this point you will want to have a look at the JSX guide if you haven't already. As previously stated, JSX is not needed but we encourage its use.

Start by creating a file named index.js in the root of shard-test and adding the needed imports and express boilerplate.

import Shard from '@visly/shard-node-server'
import * as express from 'express'
const app = express()
const port = 3000
app.get('/', (req, res) => {
res.json({hello: "world"})
})
app.listen(port, () =>
console.log(`Sample server running at http://localhost:${port}`)
)

At this point you should be able to run the server and visit http://localhost:3000 to verify that it corrrectly responds with {hello: "world"}.

> node index.js

Now we'll modify this example slightly to instead return a Shard rendered text component.

app.get('/', (req, res) => {
res.json(Shard.render(
<text>Hello World</text>
))
})

Finally we can create a custom component which encapsulates our rendering logic.

function Hello(props) {
return <text>{props.greeting}</text>
}
app.get('/', (req, res) => {
res.json(Shard.render(
<Hello greeting="Hello World"/>
))
})