Readme.md

Parse Server Backend Template (Node.js)

This repository contains the configuration file and the cloud code files for running on a Parse Server v3.x backend. The package is meant to speed up testing and deployment for when you're working on Parse Server's cloud code.

This package contains 2 apps: The Backend's cloud code and an independent Express app for web hosting and hooks. Their entry points are the files main.ts and app.ts respectively (those names are requested in order to work on an app hosted on Back4App).

More info:

• Deploy and call your first Cloud Code functions
• Hosting your Node.JS web application on Back4App servers

Content:

• Parse Server Backend Template (Node.js)
  • Template Content
    • Suggested Folder Structure
    • Modules
  • Setup and Prerequisites
    • Install Global Dependencies
    • Server Configuration
  • Editing and Building
    • Customizing System Emails and Pages
      • Building Styles
  • Running Locally
    • Testing
    • Cloning a Remote Database
  • Deploying
    • A) Deploying to Back4App.com
    • B) Deploying to remote server via SSH
  • Code Examples
    • Setup and call a cloud function
  • Credits

Template Content

Suggested Folder Structure

These folders have been pre-populated and configured for the described functions:

|-- assets            // Resource folder for accessing in runtime
  |-- templates       // EJS email templates
|
|-- config            // Database and server configuration files
  |-- credentials     // Credential files for server and database configuration
  |-- templates       // Templates for system emails
|
|-- scripts           // Chore scripts (CI, deployment, etc)
|-- src               // Main cloud code source
  |-- main.ts         // Entry point for the ParseServer
  |-- app.ts          // Entry point for a secondary Express app
  |-- env             // Environmental vars
    |-- credentials   // Credentials to be accessed in runtime
  |
  |-- hooks           // Files for managing cloud functions and jobs
  |-- modules         // Helper modules
  |-- types           // Definition files. Useful for extending @types
  |-- lib             // Shared library between frontend and backend (git-ignored)

Modules

A series of modules have been created for accomplishing common backend tasks. To use, just import and call the static classes' functions.

Module	Exported class	Description
auth.ts	Auth	Helper class for managing a super user and Roles.
currency.ts	Currency	Helper class with methods for retrieving and converting currencies.
files.ts	Files	Helper class for removing unlinked files from database objects.
jobs.ts	Jobs	Helper class for checking job status.
mail.ts	Mail	Helper class for sending emails.
setup.ts	Config	Helper class with functions for blanking and resetting the database data.
stripe.ts	Payment	Helper class and functions for managing payments with Stripe.

Setup and Prerequisites

• You'll need Node.js installed on your system.
• Run $ npm install on the root folder to install package's local dependencies.

Install Global Dependencies

1. Make sure you've installed globally parse-server and express ($ npm i -g parse-server express).

2. Install -globally- the adapters required by parse-server. You'll find them in config/parse-server.config.js. For example: $ npm i -g parse-server-mailgun:

   // parse-server.config.js
   emailAdapter: {
     module: "parse-server-mailgun",
     ...
   }

3. You may install either mongodb-runner ($ npm i -g mongodb-runner) to quickly start testing Parse Server, or MongoDB Community Edition to set up a local mongodb server instead. The latter enables your local PC to store real data instead of clearing it every time the Parse Server stops with mongodb-runner.

4. (Optional) You may want to install parse-dashboard ($ npm i -g parse-dashboard) so you see and manage your server's data.

Server Configuration

You can set the server's configuration in parse-server.config.js and parse-dashboard.config.json, inside the /config folder.

1. Set the properties appId, masterKey, javascriptKey and/or restApiKey in parse-server.config.js. The repo has some default values and you may run it with them, but you'll want to change them later on for the actual production values. See the Parse Server official guide
2. Set the same appId and masterKey in parse-dashboard.config.json (if you'll use the dashboard).

Editing and Building

Put your .ts source files for cloud code in the folder src/. The file main.ts will be the entry point. To build the code run $ npm run build. See Parse Server's Cloud Code Guide for more information.

Customizing System Emails and Pages

Emails and page templates for resetting password and verifying emails are handled internally by Parse Server. By using an email adapter you may modify how emails look; and by setting the property customPages in the server's config you can assign the desired html templates for the user-face pages. This package uses parse-server-mailgun as email adapter. You can change this configuration in config/parse-server.config.js.

You'll find these templates inside /assets/templates/system.

Important: If you're deploying to Back4App or other Parse hosting service, you may need to ask the support team to implement this configuration on their side.

Building Styles

Email templates are implementing a simplified Bootstrap theme in runtime. Make sure the css files are built and updated by running $ npm run build:scss. They should be compiled into /assets/templates/css.

Running Locally

1. Link dependencies: $ npm link parse-server, $ npm link express.
2. Start MongoDB with $ net start mongodb on Windows or $ brew services start mongodb-community on MacOS (assuming you've previously installed MongoDB) or mongodb-runner ($ mongodb-runner start).
3. Use $ npm start to run the local Parse Server (project will build before launching the server). The server will be accessible on http://localhost:1337/parse.
4. Run $ npm run dashboard (if installed) to start the Dashboard. You can access it at http://localhost:4040.
5. (Optional) To test the Express app you may need a service like ngrok.io to expose your local server to the internet.

Testing

Run $ npm test for running specs with Jasmine framework. See specs/helpers/process-env for a list of supported environmental variables.

Cloning a Remote Database

If needed, install and use the npm package mongo-clone to download a remote database.

Deploying

Use $ npm run build:prod to build in production mode.

A) Deploying to Back4App.com

Back4App provides free BaaS to host your Parse Server applications. You'll need an account to follow these steps.

1. Make sure you've installed the Back4App CLI in your system.
2. Follow the instructions to link your local back4app project.
3. Run $ b4a new inside the folder /build*.
4. Run $ npm run deploy -- --b4a to deploy your cloud code to your server on a Back4App account. The project will be compiled and uploaded immediately.

*If you've already created a project on Back4App you can run this series of commands from the project root folder:

$ b4a new
  > e                         # 'e' for existing project option
  > [your project number]     # The name of your project on back4App.com
  > build                     # Create the folder called 'build'
  > b                         # 'b' for blank project option

B) Deploying to remote server via SSH

To deploy your cloud code to a server with SSH (on Google Cloud for example), run $ npm run deploy -- --ssh.

Code Examples

Setup and call a cloud function

Once you've got the local server configured, add this code in main.ts:

Parse.Cloud.define('test', request => {
	const params = request.params;

	const result = {
		status: 'success',
		message: 'Hi, the test was successful!',
		receivedParams: params
	}

	return result;
});

Add this somewhere in the client app (browser/iOS/Android) to initialize the SDK:

// Imports
const parse = require('parse');

// Credentials:
// Use the values from the server's `parse-server.config.js`
const PARSE_APP_ID = 'yourAppId';
const PARSE_JS_API_KEY = 'yourMasterKey';
const PARSE_SERVER_URL = 'localhost:1337/parse';

// Init SDK
Parse.initialize(PARSE_APP_ID, PARSE_JS_API_KEY);
parse.serverURL = PARSE_SERVER_URL;

const params = {
	title: 'Test',
	message: 'Hi... is this working?'
}

Parse.Cloude.run('test', params).then(response => {
	console.log(response);
});

//  Console outputs:
//  {
//    status: 'success',
//    message: 'Hi, the test was successful!',
//    receivedParams:  {
//			title: 'Test',
//			message: 'Hi... is this working?'
//		}
//  }

For more information see the Parse Server's Cloud Code Guide.

Credits

Raschid J.F. Rafaelly
http://raschidjfr.dev
[email protected]

For the latest template version visit https://github.com/RaschidJFR/Parse-Server-CloudCode-Development-Unit.