[epic] v0.2: create-portal-app command and steps

[anuveyatsu]

create-portal-app command and steps to boot a new portal.

Job Story

When I'm a portal developer wanting to create a new portal I want a very simple experience (e.g. one command) to boot a new portal that i can then customize.

Approach

We are taking the modern create-react-app / create-next-app approach:

npx create-next-app
# or in yarn
yarn create next-app

BONUS 🍬 : like create-next-app it would be nice to be able to run off a template e.g.

# e.g. next.js
npx create-next-app --example with-styled-components with-styled-components-app
# We would have e.g.
npx create-portal-app --example with-drupal portal-with-drupal-as-cms

Acceptance

• I can bootstrap a frontend app using a single command
  • create-portal-app package on npm
• My boot screen looks similar to design in #35
• (BONUS) can create from examples / templates

Tasks

• Analysis and Research
  • Look at create-react-app and create-nextjs-app and evaluate which we use
  • Have an outline of how we implement based on this
• Stub package
  • Create create-portal-app MVP
  • Test Stubbed package (run locally and check if the behavior fits with requirements)
• Publish create-portal-app and make datopian the owner on npm (reserves it for later) (don't put under @datopin as that would break npx create-portal-app)
  • A couple of projects are already using Portal.js, Portaljs, Portal-js. Need to find a unique name to publish on NPM. We only need create-portal-app so not a big deal I think
• Basic working script that boots something
• Show the welcome screen
• Publish to npm and have it owned by Datopian
  • ❓ script for auto doing this

Analysis

Our approach is different frontend v2 (compositional vs inheritance)

Instead of developing themes, we want to be able to init the frontend app and customize as per our needs. For example, have a look how the following frameworks work.

Inspiration

• Create React App: https://github.com/facebook/create-react-app
  • init command: npx create-react-app my-app-name
    • you can also npm init react-app my-app-name or yarn create react-app my-app-name
  • run server: npm start
• GatsbyJS: https://github.com/gatsbyjs/gatsby
  • init command: gatsby new my-blazing-fast-site
    • requires pre-installing cli tool: npm install -g gatsby-cli
  • run server: gatsby develop

In GatsbyJS, you first need to install CLI tool that helps you to init an app, start server etc. We want to simplify the process and use Create React App style => use npx for initiating the app and then we can use npm run ... commands for running server etc.

npx is a very powerful command that's been available in npm starting version 5.2

How does npx works?

npx create-react-app my-cool-new-app installs a temporary create-react-app and calls it, without polluting global installs or requiring more than one step!

Research on create-xxx-app in detail

• FB create-react-app
  • uses js
  • older
  • LoC:
• create-nextjs-app
  • uses typescript ( Mostly JS not much Typescript )
  • newer
  • LoC:

FB create-react-app

https://github.com/facebook/create-react-app

https://github.com/facebook/create-react-app/blob/master/tasks/cra.js

Main file for managing all the params for creating react app. tasks/cra.js -> from package.json

• Specific code

package.json - https://github.com/facebook/create-react-app/blob/master/package.json#L7

"scripts": {
    "build": "cd packages/react-scripts && node bin/react-scripts.js build",
    "create-react-app": "node tasks/cra.js",

cra.js - https://github.com/facebook/create-react-app/blob/master/tasks/cra.js

Child processes here that are used to create project dir.

create-nextjs-app https://github.com/vercel/next.js

Codebase here for next: https://github.com/vercel/next.js/tree/canary/packages/create-next-app

Also let's clean the codebase to use either javascript or typescript. Right now its mixed for open source repo.

package.json

• builds index.ts to dist and then that is what is packaged as the script ...

  "bin": {
    "create-next-app": "./dist/index.js"
  },
  
  ...
  
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "ncc build ./index.ts -w -o dist/",
  },

index.ts - https://github.com/vercel/next.js/blob/canary/packages/create-next-app/index.ts

Calls this sub lib

• Use commander to parse arguments and provide context
  • https://github.com/tj/commander.js
• Chalk for terminal string styling
  • https://github.com/chalk/chalk
• Create an example directory (if doesn't exist)
• Initialize a git directory for generated app
• Download and unpack the app from github
• Create app requires following params
  • appPath
  • useNpm
  • useYarn
  • example
  • examplePath
• Helpers like
  • downloadRepo
  • isRepo
  • URL gives 200 status code
  • extract the tar file
  • downloadExampleRepo

[cotts]

I finish those tasks and created pull request #52, but I need to be validated before stub package.

• Analysis and Research
  • Look at create-react-app and create-nextjs-app and evaluate which we use
  • Have an outline of how we implement based on this

[rufuspollock]

@cotts can you update the acceptance section in bold with what you've done and we'll look at PR.

[rufuspollock]

@cotts can you update the main issue tasks and acceptance as per https://playbook.datopian.com/issues-tasks/#completing-tasks and then close this as FIXED if it is done (or flag what is not done).

[cotts]

@rufuspollock , I updated the related tasks and the label, but before continue, I think it can't be closed yet because there are more things to accomplish and test before publishing.
I still need some validation about the MVP of the script before going to the next step.

[rufuspollock]

FIXED / WONTFIX. We created a working create-portal-app https://github.com/datopian/portal.js/tree/4a6577fd38d482696e27492bd166050495bc0c4c/packages/create-portal-app. However, for now we are parking and won't go further as we are not sure a separate create-portal-app (vs e.g. piggy-backing on next-create-app) so closing.