What is StartupJS?

StartupJS is a full-stack framework that consists of:

• Frontend: Isomorphic React native and web
• Backend: ExpressJS
• Collaborative Database: MongoDB which runs behind ShareDB and a client-server observable ORM

Quickstart

Requirements

StartupJS app requires: Node 14.x, Yarn, MongoDB 4.x, Redis 5.x

Alternatively, you can run everything in Docker, in which case follow Docker development Quick Start. Important to note is that Docker won't allow you to test Android or iOS.

Installation

1. Initialize a default ui template project, change myapp to your project name (use lower case):

   npx startupjs@latest init myapp
   

2. Go into the created project folder and start the web application with:

   yarn start
   

3. Open http://localhost:3000 and start developing!

Native Development (iOS and Android)

Requiremens

Follow the React Native guide to setup everything. StartupJS uses native modules, so you have to follow React Native CLI Quickstart, not the Expo guide.

How to run StartupJS on native

yarn start actually combines 2 commands together: yarn server and yarn web.

In order to develop your app on mobile, you'll have to open a bunch of tabs anyways, so it makes sense to also run server and web separately instead of using the yarn start.

Here is the list of commands to run all platforms at the same time:

1. Start server (required) in a separate terminal tab

   yarn server
   

2. Start web (optional) in a separate terminal tab

   yarn web
   

3. Start metro (required for Android and/or iOS) in a separate terminal tab

   yarn metro
   

4. Run android (optional) in a separate terminal tab

   yarn android
   

5. Run ios (optional) in a separate terminal tab

   yarn ios
   

IDE configuration

Step 1: Add support for PUG syntax highlighting

1. Install extension vscode-react-pug
2. Restart VS Code

Step 2: Add support for ESLint errors highlighting

1. Install extension ESLint
2. Restart VS Code

Step 1: Add support for PUG syntax highlighting

1. Install packages language-babel and language-pug
2. Open settings of language-babel in atom
3. Find the field under "JavaScript Tagged Template Literal Grammar Extensions"
4. Enter: pug:source.pug
5. Go to Core settings of atom.
6. Uncheck Use Tree Sitter Parsers
7. Restart Atom

Step 2: Add support for ESLint errors highlighting

1. Install package linter-eslint
2. Restart Atom

Documentation

The main things you'll need to know to get started with StartupJS are:

1. React Native
2. Racer's Model. You only need to read the MODELS section, ignore everything else.
3. React hooks for Model
4. StartupJS UI Components

Before launching your app to production you are strongly encouraged to implement:

1. Security

For additional documentation on each StartupJS package see the according readme

Advanced

To gain further deep knowledge of StartupJS stack you'll need get familiar with the following technologies it's built on:

1. React and/or react-native-web for the Web-frontend.
2. React Native for the Native-frontend (iOS, Android, etc.).
3. Pug which is used besides JSX for templating.
4. Stylus which is used besides CSS for stylesheets.
5. React-ShareDB:
   • A ShareDB real-time collaborative database integration into React.
   • Allows to sync data between your local state (similar to Redux) and the DB.
   • Brings in collaboration functionality similar to Google Docs, where multiple users can edit the same data simultaneously.
   • Uses WebSockets to send micro-patches to and from the server whenever there are any changes to the data you are subscribed to.
   • Uses observables to automatically rerender the data in React, similar to MobX.
6. Model based on Racer with an ability to create custom ORM methods.
7. React Router for routing and navigation with an ability to separate your frontend into multiple frontent mircoservices (e.g. main and admin)
8. Node.js and Express for the backend.
9. MongoDB for the database.
10. Redis for the pub/sub (required by ShareDB) and locking functionality.
11. Code Quality control tools:
    • ESLint
    • optional TypeScript

Sub-Packages Documentation

• App
• Babel preset startupjs
• Backend
• Bundler
• CLI
• CodePush
• Cron
• Docs
• Hooks
• Init
• Model
• Offline
• ORM
• React sharedb
• Routes middleware
• Server
• StartupJS meta package
• UI

Official App Templates

The following templates are available:

1. simple
2. routing - plugs in @startupjs/app which provides a react-router routing implementation
3. ui (default) - plugs in routing and @startupjs/ui

By default init creates a project using the feature-rich ui template.

To use another template specify the -t option:

npx startupjs init myapp -t simple

To create a new project using an alpha version of startupjs, append @next to the startupjs itself:

npx startupjs@next init myapp

Each template initializes on top of a default react-native init application.

If you want to use an RC version (next) of react-native, specify it using the -rn option:

npx startupjs init myapp -rn next

Docker development Quick Start

Alternatively you can run a docker development image which has node, yarn, mongo and redis already built in. You only need docker for this. And it works everywhere -- Windows, MacOS, Linux.

Keep in mind though that since docker uses its own driver to mount folders, performance (especially when installing modules) might be considerably slower compared to the native installation when working with the large amount of files.

1. Initialize a new ui boilerplate project. Change myapp at the end to your project name (use lower case).

   docker run --rm -it -v ${PWD}:/ws:delegated startupjs/dev init myapp
   

2. Go into the created project folder. Then run the development docker container with:

   ./docker
   

3. While inside the running container, start your app with:

   yarn start
   

4. Open http://localhost:3000 and start developing!

5. When you want to open an additional terminal window, you can quickly exec into the running container using:

   ./docker exec
   

Version migration guides

The following guides are available to assist with migration to new major versions of StartupJS:

• Migration Guides

Vite

You can configure your project to use vite in development for web client instead of Webpack.

Vite provides faster compilation times since it uses native ES Modules and compiles only the files which are actually being used on the page you are viewing.

IMPORTANT things to note:

1. Only the simple template is supported out of the box by our Vite plugin.

2. Most react-native libraries name files containing JSX as simply .js, while Vite expects such files to be named .jsx. Because of that you might need to alter Vite config to force it to compile .js files in node_modules the same as .jsx.

How to use:

Install simple starter project with npx startupjs init myapp -t simple and follow instructions in the according plugin package:

• @startupjs/vite-plugin-startupjs

Security

StartupJS server is designed to be secure by default.

For the sake of simplifying quick prototyping, a new project you create with startupjs init will have security mechanisms turned off.

You are strongly encouraged to implement security for your project as early as possible by removing secure: false flag from the server initialization in your server/index.js file.

There are 3 types of security mechanisms you must implement:

• Access Control to MongoDB documents
• Server-only MongoDB Aggregations
• Validation of MongoDB documents using JSON Schema

If you want to work on their implementation one by one, you can keep the secure: false flag and only add the ones you want to implement by specifying the following flags:

accessControl: true,
serverAggregate: true,
validateSchema: true

NOTE: All 3 mechanisms are integrated for their simpler use into the ORM system. We are working on a guide on how to use them with the ORM. If you want help properly integrating it into your production project, please file an issue or contact cray0000 directly via email.

Contributing & Troubleshooting

See CONTRIBUTING.md

Licence

MIT

© Pavel Zhukov