This package has been deprecated

Author message:

This package is no longer being maintained

prismic-express

Static site generator + development server for Prismic.io data in Node.js.

Table of Contents

• Install
• Usage
• Routes
• Templates
• Static pages
• Scaffold
• Config.js
  • Prismic
  • Server
  • Template
  • Build
  • Static
  • Source
  • API
  • Ignore
  • Mapping
  • Webapp
  • Sitemap

Install

npm install prismic-express -g

Usage

New Project

mkdir my-project
 
cd my-project
 
prismic-express init

Run Server

prismic-express server

Run Sync

prismic-express sync

Run Build

prismic-express build

Print Help

prismic-express help

ProperJS/App scaffold

When using the default client-side application scaffold, you can start the project using bin scripts. This boots the dev server and runs webpack.

./bin/start

Routes

This tool maps your Prismic customTypes to a node dev server and a static site builder. How does that work?

If you have a customType called Foo with an id of foo you get the following routes:

/foo/
/foo/:id

The first one is a listing of all documents for the customType. The second one is a single document post by ID. No data from Prismic is altered in any way before passing it to your templates.

Templates

Your templates are generated in a similar way to how the routes are mapped. For each customType you get an document.html and an documents.html template. So, for Foo you get the following:

template/
    foo/
        document.html
        documents.html

The default template language is ejs. This tool uses consolidate so you can use any of the supported languages there. You need to provide the template engine you wish to use. Say you would like to use mustache. You would do the following:

Install mustache as a local dependency for your project.

npm install mustache --save-dev

Provide the mustache ref to consolidate through config.js.

{
    template: {
        lang: "mustache",
        engine: require( "mustache" )
    }
}

The following data context is exposed to all templates. The caveat being that document and documents are contextual to whether you are looking at a customType list of documents or a single document by customType.

{
    static: {object},
    staticPages: {array},
    customTypes: {array},
 
    // Exposed to document.html
    document?: {object},
 
    // Exposed to documents.html
    documents?: {array}
}

Static Pages

Any .html file created in the templates root directory will be generated into a static page with no context data from Prismic. So, about.html becomes /about/ as an active route. By default the index.html template is reserved as the homepage.

Scaffold

A scaffold is generated for you in the directory you call prismic-express init within. This starts your templates for the dev server and site generator.

It also pulls in ProperJS/App as your client-side application scaffold. Check the ProperJS/App readme for more on this.

If you don't want to use ProperJS/App, simply trash it and start from scratch or use some other boilerplate you prefer.

.gitignore
config.js
package.json
README.md
source/
static/
template/
webpack.config.js

Config.js

The config.js file is your settings file for this tool.

Prismic Config

You must add your prismic apiAccess endpoint. If you enabled Repository Security you must also add your accessToken.

"prismic": {
    "apiAccess": "https://your-project.cdn.prismic.io/api"
    "accessToken": "your access token if you enabled this feature"
}

Server Config

This sets the default port for the dev server to run on.

"server": {
    "port": "1337"
}

Template Config

This sets the default template language and directory root for templates.

"template": {
    "root": path.join( __dirname, "template" ),
    "lang": "ejs"
}

Build Config

This sets the default directory for generating static site builds.

"build": {
    "root": path.join( __dirname, "build" )
}

Static Config

This sets the default paths for your static site assets. Your webpack.config.js file uses these as well.

"static": {
    "root": path.join( __dirname, "static" ),
    "css": "/css/",
    "js": "/js/",
    "images": "/images/",
    "fonts": "/fonts/"
}

Source Config

This sets the default path for your source application files - Javascript and SASS.

"source": {
    "root": path.join( __dirname, "source" )
}

API Config

You can generate json endpoints to serve data to your client-side application as raw JSON. Here's an example that would give you the endpoint /api/data.json. Currently this will serve all documents that have been synced.

"api": ["data"]

Ignore Config

Most likely you'll not want all of your customTypes to have a routing map. You can use the ignore field to specify an array of customTypes to omit from routing and templating.

"ignore": ["foo", "bar"]

Mapping Config

You can specify data mapping to customType routes and static page routes using the mapping option. You can also specify * to map certain data to all routes.

"mapping": {
    // Map set of customTypes to homepage, "/"
    // This will include all documents for all customTypes mapped
    "index": ["foo", "bar"],
 
    // Map a single document to a static page, "/about/"
    // This will include the single document that is mapped by customType
    "about": {
        // The customType
        "type": "page",
 
        // How to match an document by a field value
        "document": {
            "field": "name",
            "value": "Foo"
        }
    }
}

Webapp Config

If you are developing a single page webapp and want all of your requests to bounce off ./template/index.html.

"webapp": true

Sitemap Config

This sets the customTypes you want used to generate a sitemap.xml file for your site. You can also specify static pages to include as well. The slugField option can be used to specify a data field to be used as the url slug for the documents in question. Prismic is weird with this. They slug field is deprecated. If slugField is present that will be used. Otherwise we will try to use the first value in the slugs array for a document. Next we try the documents uid. Lastly we will fall back on the documents id.

"sitemap": {
    "baseUrl": "http://foo.com",
    "slugField": "name",
    "customTypes": ["foo", "bar"],
    "staticPages": ["about", "me"]
}

Pull Requests

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request