stancy v1.0.0-alpha.28
Stancy
Stancy uses static files and folders to generate a database of collections and items. The database can be queried as a plain object, outputted as a json file, or served using an express server for a RESTlike API. This is useful for building static sites which use frameworks like React, Vue, Svelte or Marko. Stancy is unbiased about how you use it and can be customised to suit different use-cases.
Example
In this example, we'll look at how we can create a database from static files and folders which can be accessed using an API for a website.
Start by creating a folder with some content, below is an example. Each top level file or folder creates a root endpoint.
content/
site.json
pages/
home.md
about.md
services.md
blog/
index.md
my-first-post.md
another-post.md
Here we've created a file site.json
which stores key information about our site, some pages
, and a blog
.
Now start the server.
stancy('content/').serve(3000, '/api/')
We can access the content using the following requests:
- localhost:3000/api/site
- localhost:3000/api/pages
- localhost:3000/api/pages?status=draft
- localhost:3000/api/pages/about
Items in collections can be filtered by querying their fields. For example the query ?status=draft
will list all draft pages.
Check out the examples.
Installation
Add the npm package to your project.
npm install stancy --save-dev
Import stancy in your application.
import stancy from 'stancy'
Features
Server and client
Easily serve content from static folders and files, and fetch content.
Collections and Items
Collections are created by plural sounding folders. Items are created using folders.
Preprocess data
Easily sort collections, format dates, and parse content on the client.
Index File
This is useful if you prefer to organise using folders or if you want to create an index page for a group of related content.
# Creates a collection of items posts/ item-one.md item-two.md item-three.md # Creates an item item/ index.md
Hidden
Prepend an underscore to hide a file or folder. In the case of hiding a folder, this will also hide all it's contents.
_file-is-hidden.md _folder-is-hidden/
File Types (Planned)
The following file types are supported.
- Archives
- Audio
- Code
- Documents
- Images
- Videos
Meta Data (Planned)
You can add meta data to images by creating a data file with a matching name.
my-first-post/ playing-frisbee.jpg playing-frisbee.yml
This will create the following image meta data
{ // ... "images": [ { "src": "/static/playing-frisbee.jpg", "alt": "Me playing frisbee" } ] }
Built in Fields
If you create a database you can filter and show data using a query language of your choice using the following field names.
Private
_name
Name of the resource_collection
Collection the resource belongs to_index
The index of the resource in the collection or dataset_type
The type of resource. Named after the folder or file._source
The path to the folder containing the file.
#### Public
- `url` The url to the resource.
Docs
Starting a server
stancy(source).server([port, path])
Arguments
source
{ String } source of the content directory to be serveredport
{ Number }path
{ String } subpath where API will be accessible fromExample
stancy('content/').server(3000, '/api/')
Starting a client
stancy([source]).client(url)
Arguments
url
{ String } url of the production server
#### Example
```js
stancy('content/').client('http://domain.com/api/')
```
Preprocessing data
client.preprocess([type,] callback)
Useful for sorting collections, formatting dates, or parsing markdown.
Arguments
type
{ String } can be one of the following:collection
returns every collection as an array of objects.item
returns every item as an object with key value pairs.content
returns value of every item with a property of content.
callback
{ function } gives access to one of the types ofdata
above.Examples
An example of sorting collections by date
client.preprocess('collection', (data) => { return data.sort((a, b) => { if (a.date > b.date) { return 1; } else if (a.date < b.date) { return -1 } else { return 0 } }) })
An example of formatting machine readable dates
client.preprocess('item', (data) => { return data.date = new Date(data.date) })
An example of parsing markdown
client.preprocess('content', (data) => { return marked(data) })
Getting data
client.get('users/jerry').then(res => { console.log(res) }).catch(err => { console.log(err) })
Example response
{ "url": "users/jerry", "name": "Jerry", "age": "24", "role": "admin", "content": "<h1>Jerry</h1>" }
Creating a database
stancy(source).database()
Example
var database = stancy('content/').database()
Configure using config file (Planned)
stancy.config.js
{ source: 'content/', client: { production: 'https://stancy.now.sh/api/', token: 'T89ALS90', preprocess: ({content}) => { content = marked(content) } } }
Specify custom config file
stancy().config('src/stancy.config.js')
Development
To install the dependencies
npm install
To run the demo server
npm run demo
To run tests
npm run test
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago