ApostropheCMS Essentials Starter Kit

Requirements For Development On Your Computer

Operating System: Mac, Linux, or Virtual Linux

Your local development environment must be either MacOS or Linux. If your development computer runs Windows, we recommend development on Windows Subsystem for Linux (WSL). Microsoft recommends WSL for Node.js development.

Software Installation Requirements

To test-drive the project in development, make sure you have Apostrophe's usual dependencies on your local machine:

• MongoDB (5.x or better, we recommend 6.x or better) or an Atlas account
• NodeJS (18.x or better)

For more information see the Apostrophe Getting Started Tutorial.

Getting started

This Starter Kit, also known as a boilerplate project, serves as a template for initiating new projects and can be installed in two main ways:

1. Using npm create: This clones the template locally, installs its dependencies, and sets up an initial admin user. You accomplish this using:

   npm create apostrophe@latest <my-project-name>

Note that if you are connecting to an MongoDB Atlas instance you should add your connection string to the APOS_DB_URI environment variable first. Use:

export APOS_MONGODB_URI="mongodb+srv://username:pa%24%24word@mycluster.1234x.mongodb.net/YOUR-PROJECT-NAME?retryWrites=true&w=majority"

2. Manual Setup: Manually git clone this repository and install its dependencies using npm install. Then add an initial admin user with node app @apostrophecms/user:add admin admin. Again, if using a MongoDB Atlas instance set the APOS_MONGODB_URI environment variable first using:

export APOS_MONGODB_URI="mongodb+srv://username:pa%24%24word@mycluster.1234x.mongodb.net/YOUR-PROJECT-NAME?retryWrites=true&w=majority"

For those who need to create multiple projects with additional base modules, consider forking this repository into your organizational or personal GitHub account. Customize it to fit your needs, then clone it directly:

git clone https://github.com/<your-account>/<repo-name> <project-name>

After cloning, set shortName in app.js and name in package.json to your project name, run npm install, and add an admin user with node app @apostrophecms/user:add admin admin.

Note: This template is NOT designed to be installed into an existing project.

Running the project

Run npm run dev to build the Apostrophe UI and start the site up. Remember, this is during alpha development, so we're all in "dev mode." The dev script will watch for saves in client-side CSS and JavaScript and trigger a build and page refresh if they are detected. It will also restart the app when server-side code is saved.

Making it your own

This boilerplate is designed so you can install and start running it right away. If you are starting a project that will go into production one day, there are a few things you should be sure to check:

• [ ] Update the shortname. You don't need to perform this step if you created your project using the CLI tool. The shortname option in app.js is used for the database name (unless another is given in the @apostrophecms/db module). You should change this to an appropriate project name before you start adding any users or content you would like to keep.
• [ ] Update the Express.js session secret. The secret is set to undefined initially in the modules/@apostrophecms/express/index.js file. You should update this to a unique string.
• [ ] Decide if you want hot reloading on. This boilerplate uses nodemon to restart the app when files are changed. In modules/@apostrophecms/asset/index.js there is an option enabled to refresh the browser on restart. If you like this, do nothing. If you don't, remove the option or set it to false. The option has no effect when the app is in production.
• [ ] Update the className options in app.js. This option is set for core widget types to provide CSS styling hooks. It is namespaced with bp- for "boilerplate." You will likely want to update that to match your general CSS class naming practices.

You really want the docs

Right now, all the juicy info is in the ApostropheCMS docs, so head over there and start reading! This boilerplate project is a fun introduction to the UI, but you'll want to know more to really try it out.