UI Email Builder CMS

This repo contains the New Jersey Email Builder CMS. It is a static site buit with Gatsby and uses Decap CMS to update. The intent is to give the Innovation Team the ability to log in to the admin site and create email templates which they can view using the live preview. Once they publish a template, they can grant access to someone. The grantee can then upload details like their Seal and add any necessary information, while looking at a live preview of the email that will be generated. Once they are finished, they can click a button and receive the email html.

Site Admin

Site admins can sign in with Github through the root admin page at example.org/admin. Once they're signed in they can create, update, or delete email templates. Example email templates could be "Benefits Expiring Soon" or "Reminder to Register." Making changes to the email templates will change YAML files in the content/email-templates folder of this repository. This causes the application to redeploy. During deployment Gatsby will see the changes in content/email-templates and generate new and additional HTML pages based on them.

Technologies

This application uses the following technologies:

• Decap CMS
• Gatsby
• React
• NodeJS
• TypeScript
• Jest

Deployment

More to come. Netlify? Amplify? Something else?

Development

Requirements

Installation

You should have NodeJS v18.3.0 or higher installed.

1. Clone the repo with git clone git@github.com:newjersey/ui-email-builder-cms.git
2. Install dependencies with npm install

Running the Development Server

To work on this project locally:

1. Run the development server with npm run develop
2. Visit localhost:8000/ to visit the homepage and localhost:8000/admin to visit the admin interface

Using Decap Locally

The following is adapted from the Decap docs.

1. Run npx decap-server
2. In a different terminal pane or window run the development server with npm run develop

Now any changes you publish in Decap CMS on your local machine will appear in your local repository.

Linting

To see which files are different, run npm run lint. To have automatically correct any lint errors run npm run lint:fix.

Testing

Testing is done using Jest. The tests can be run with npm run test or in watch mode with npm run test:watch. For convenience, you can run npm run validate which will typecheck (npm run typecheck), lint (npm run lint), and run the tests.

Config

There are several environment variables that are required in order to use the application

• GATSBY_APP_MODE: ['NJ' | 'All'] - controls which email templates are visible in the app.
• GATSBY_BACKEND_FLAG: boolean - controls whether backend-specific features such as logging in and saving templates are accessible to users.
• GATSBY_BACKEND_URL: string - the url for the serverless application allowing access to log in, save templates, and export .png images
• NODE_ENV: ['development' | 'production'] - determines whether the frontend application is running locally or at a specified url. Used mostly for local links and images.

And one optional environoment variable

• GATSBY_LOG_EDITS: boolean - when true, it logs a json object to the browser console describing the component being edited, which (once converted to yaml) can be used as the defaultValue for that component in an email template

Decap

The Decap CMS config is located at static/admin/config.yml. However, the src/cms/cms.tsx file initializes the application with an override that sets local_backend: true in development environments. This takes precedence over anything in static/admin/config.yml.

Jest

Testing is configured across several files:

• loadershim.ts
• jest.config.ts
• jest-preprocess.ts
• setup-test-env.ts

This setup was adapted from the Gatsby testing docs.

File Generation

At the end of the day, the deployed application is a set of static files (HTML, CSS, and JavaScript). These files are generated by Gatsby in one of two ways: Either React code in src/pages or generated from YAML files in content using templates found in src/templates. The code that combines these two sources to generate files is gatsby-node.ts.