startupjs/deploy repository overview

⁠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 init myapp
   

   Copy

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

   yarn start
   

   Copy

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
   

   Copy

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

   yarn web
   

   Copy

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

   yarn metro
   

   Copy

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

   yarn android
   

   Copy

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

   yarn ios
   

   Copy

⁠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⁠

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
   

   Copy

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

   ./docker
   

   Copy

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

   yarn start
   

   Copy

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
   

   Copy

⁠Version migration guides

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

• Migration Guides⁠

⁠Advanced usage

You can configure your project to use vite⁠ in development for build process.

yarn add [email protected] vite-plugin-startupjs

And add the execution of vite patch to your postinstall script in package.json:

  "postinstall": "startupjs postinstall && npx patch-package --patch-dir ./node_modules/@startupjs/patches/vite"

Note that the vite version is required to be the outdated 0.20.3. lUpgrade to the latest vite version is planned to be done soon.

⁠Contributing & Troubleshooting

See CONTRIBUTING.md⁠

⁠Licence

MIT

© Pavel Zhukov