Cloudraker's Apostrophe Boilerplate

This boilerplate is a minimal starting point for Apostrophe 2 projects built by CloudRaker.

Creating a project using this Boilerplate

npm install -g apostrophe-cli && \
apostrophe create-project <shortname-without-spaces> --boilerplate https://github.com/CloudRaker/apostrophe-boilerplate.git

---

Table of contents

• Getting Started
  • Install Technical Requirements
  • Start Database Services
  • Create Admin User Account
  • Run Site Locally
• Development
  • Post-Clone Chores
  • NPM Scripts
  • Brunch
  • Extending and Creating Apostrophe Modules
  • Apostrophe Config
• References

---

Getting Started

To get started, we recommend taking a look at the guide to create your first Apostrophe project. You could also take a look at Apostrophe's CLI or simply fork this repository.

Install Technical Requirements

• Node Version Manager.
  • This project requires **Node >=8 <10 **.
  • You can check which version of Node is currently in use by running nvm current in a Terminal instance.
  • In the case you have a different version running, you can install the latest v8.x by running nvm install 8.

The following components can be installed with Brew, if they are not already available on your machine:

• MongoDB

brew install mongodb

• Redis

brew install redis

Start Database Services

At this point, start the services by running these commands one at a time:

• Start Mongodb

brew services start mongodb

• Start Redis

brew services start redis

Create Admin User Account

With Apostrophe installed, the first thing to do create an admin user account so you're able to log into the CMS. Run the following command (this will prompt you for a password).

node app.js apostrophe-users:add admin admin

Run Site Locally

Now you're all set!

• Run npm run start in a Terminal instance to start up the local server.
• Head to localhost:3000 in your web browser.

---

Development

Post-Clone Chores

Update NPM Dependecies

Once the project is cloned and once the Node modules are installed, it might be a good idea to update the dependencies and devDependencies list package.json so that the project is explicitly depending on the latest versions.

You may run npm outdated to easily obtain a list of outdated packages.

NPM Scripts

There are a few scripts available in the package.json:

• npm run start: Starts the app and makes it visible at localhost:3000 in a browser.
• npm run debug: TBD
• npm run debug-monitor: TBD
• npm run dev: Starts the app, and rebuilds/reloads when changes are made to files that are watched.
• npm run njk: (Deprecated) Renames all *.html files to *.njk.

Brunch

Apostrophe uses LESS as a CSS preprocessor. However, for our projects, we wish to use SASS. Also, we wish to use ES6, which is not available by default with Apostrophe projects.

In order to do so, Brunch was chosen to compile ES6 JavaScript and SASS files.

You most likely will not need to run this script directly, as it is used by the npm run dev script. Contact a CloudRaker dev admin if you need more information.

Extending and Creating Apostrophe Modules

With Apostrophe, you extend their modules and create new ones, all in the lib/modules directory.

Naming Conventions

When creating new modules, the convention is to prefix their an abbreviation of the project name. For example:

• cr- for CloudRaker (e.g. cr-careers-pages, cr-social-links-widgets)

Apostrophe Config

Not much is to be edited from the config located at ./apos-config.js, but at least these elements should be:

• aposOptions.shortName: Currently set by default as 'apostrophe-boilerplate', it should be set as the project name.
• aposOptions.modules.apostrophe-admin-bar: The custom content should actually be customized.

Otherwise, the modules defined in the lib/modules directory will be added by ...customModules rest parameter at the end of the modules definition.

In order for this to work, you will need to replace ^custom- in the customModuleNames variable with the prefiix you chose in the last section (ex. ^cr-)

const customModuleNames = fs.readdirSync(path.resolve(__dirname, 'lib', 'modules'))
.filter(dp => /^custom-/.test(dp));

---

References

• Apostrophe 2 documentation site
• Apostrophe CLI
• Apostrophe guide to creating your first project