Quick start guide

For experienced developers, a list of tasks to get started with the framework as quickly as possible.

This guide will step through creating a new project using the BaseCMS Website Framework.

Dependencies

Install the Marko Web framework and the web CLI utility:

npm i --save @parameter1/base-cms-web-cli @parameter1/base-cms-marko-web @parameter1/base-cms-marko-core

Required files

the BaseCMS Website Framework makes a couple of assumptions: You're running a website, and you intend for users to access it via a browser (rather than just being a headless API.)

To that end, the following two files must be created within your project:

The site CSS file

The site CSS file must be created at server/styles/index.scss within your project.

body {
  color: #888;
}

The site JS file

The Vue.JS file must be created at browser/index.js within your project:

import Browser from '@parameter1/base-cms-marko-web/browser';
export default Browser;

Required environment variables

The following are the minimum required variables to use the framework. If you don't have these values available, feel free to reach out to us via [email protected] and we can supply them!

Key	Type	Description
TENANT_KEY	string	The BaseCMS tenant key
SITE_ID	string	The BaseCMS site id
GRAPHQL_URI	URI	The URI to use to connect to a BaseCMS GraphQL server.
RSS_URI	URI	The URI to use to connect to a BaseCMS RSS server.
OEMBED_URI	URI	The URI to use to connect to a BaseCMS OEmbed server.
SITEMAPS_URI	URI	The URI to use to connect to a BaseCMS Sitemaps server.

We recommend using Docker Compose and the envalid package to manage environment variables within your project. This is also repackaged under the @parameter1/base-cms-env package, which you can install with npm

Create an env.js file:

const { cleanEnv, validators } = require('@parameter1/base-cms-env');

const { nonemptystr } = validators;
const toApply = ['TENANT_KEY', 'SITE_ID', 'OEMBED_URI', 'GRAPHQL_URI', 'RSS_URI', 'SITEMAPS_URI'];

module.exports = () => {
  const envs = cleanEnv(process.env, {
    TENANT_KEY: nonemptystr({ desc: 'The BaseCMS tenant key.' }),
    OEMBED_URI: nonemptystr({ desc: 'The BaseCMS OEmbed URI.' }),
    GRAPHQL_URI: nonemptystr({ desc: 'The BaseCMS Graph URI.' }),
    RSS_URI: nonemptystr({ desc: 'The BaseCMS RSS URI.' }),
    SITEMAPS_URI: nonemptystr({ desc: 'The BaseCMS Sitemap URI.' }),
  });
  // Set the values back to the process' environment variables
  toApply.forEach(k => process.env[k] = envs[k]);
  return envs;
};

Create a .env file:

TENANT_KEY=some_key
SITE_ID=some_site_id

OEMBED_URI=https://caprica.oembed.base-staging.parameter1.com
GRAPHQL_URI=https://caprica.graphql.base-staging.parameter1.com
RSS_URI=https://caprica.rss.base-staging.parameter1.com
SITEMAPS_URI=https://caprica.sitemaps.base-staging.parameter1.com

Creating a template

Create a server/templates/home-page.marko template:

$ const { req } = out.global

<marko-web-document>
  <@above-container>
    <h1>Hello, World!</h1>
    <blockquote>
      From: ${req.hostname}
    </blockquote>
  </@above-container>
</marko-web-document>

Configuring the framework

Create an index.js file:

// set up our env vars first
require('./env')();

const { startServer } = require('@parameter1/base-cms-marko-web');
const template = require('./server/templates/home-page');

module.exports = startServer({
  rootDir: __dirname,
  routes: app => app.get('/', (_, res) => res.marko(template)),
});

Starting it up

Run your site:

node ./node_modules/.bin/basecms-website dev index.js

By default, your application will be available on localhost on port 4008. To override this, set the PORT environment variable.

Your new website. Stunning, no?