Skip to content

Latest commit

 

History

History
466 lines (406 loc) · 17.9 KB

README.md

File metadata and controls

466 lines (406 loc) · 17.9 KB
                         __
                        /\ \__
  ___  _ __   __     __ \ \ ,_\    __
 /'___/\`'__/'__`\ /'__`\\ \ \/  /'__`\
/\ \__\ \ \/\  __//\ \L\.\\ \ \_/\  __/
\ \____\ \_\ \____\ \__/.\_\ \__\ \____\
 \/____/\/_/\/____/\/__/\/_/\/__/\/____/
  ___      __  __  __  __
/' _ `\  /'__`/\ \/\ \/\ \
/\ \/\ \/\  __\ \ \_/ \_/ \
\ \_\ \_\ \____\ \___x___/'
 \/_/\/_/\/____/\/__//__/
   __    _____   _____    By: The Qodesmith
 /'__`\ /\ '__`\/\ '__`\
/\ \L\.\\ \ \L\ \ \ \L\ \
\ \__/.\_\ \ ,__/\ \ ,__/
 \/__/\/_/\ \ \/  \ \ \/
           \ \_\   \ \_\
            \/_/    \/_/

Create New App · npm version

Create full-stack React applications! All the tech you've come to know and love - React, Express, & MongoDB. Use some, use none, but always use React ;)

The Why

You want to make apps. You want to make apps with React. Excellent choice.

Create React App is awesome, no doubt, but your app needs an API - so you look to Express. Heck, you might already have an API! But how to integrate it? And to top it off, you like using JavaScript up and down the stack, so your persistence layer is MongoDB. But CRA doesn't give you all of this out of the box. What's a developer to do?

Create New App, that's what you do!

It's just like CRA but with full stack options - and more! You get a Webpack development server, a build which ties all-the-things together, the fancy new React Fast Refresh, and a custom SCSS utility library named Sassyons - atomic CSS anyone? Optionally include React Router, Express, and MongoDB. Don't need some of the goodies included? No worries! A few CLI flags and you're off to the web development races with whatever it is you do need. No ejecting either. Everything is set up for you, loaded with comments and links, and ready for your tweaking - or not. You're gonna like this. I promise.

Installation

npm install -g create-new-app

Usage

Guided Process

It couldn't be easier to use Create New App. Simply type create-new-app (or cna for short) and you'll start the guided process:

  1. Enter a name for your app
  2. Would you like to include React Router?
  3. Would you like to include an Express server?
  4. Would you like to include MongoDB?

Manual Options

Simplest example: create-new-app <app-name>
^^^ #Boom. Your app is running on http://localhost:8080.

Want the full control of all the options? No problem:

create-new-app <app-name> [options]

# Shorthand:
cna <app-name> [options]

Sandbox Project

Sometimes you simply want a quick sandbox project to test something real quick. Maybe in order to test a simple function or some CSS. Create New App has you covered:

cna <app-name> --sandbox

This will generate 3 files for you, tied together in index.html:

  1. index.html
  2. main.js
  3. styles.css

Simple, no? Let's look at some other examples...

Other Examples

# Let the guided process walk you through it:
create-new-app

# You already have a local API built & running at `localhost:1234`:
create-new-app awesomeness --api / --apiPort 1234

# Perhaps all requests to that local api are behind the `/api` flag:
create-new-app awesomeness --api /api --apiPort 1234

# You've decided you want a new API. Express is set up for you:
create-new-app awesomeness -e

# You want a new API with MongoDB wired up & ready to go:
create-new-app awesomeness -m

Webpack Magic

Webpack 5!!! While Webpack certainly seems like magic, let's just go over what that "magic" is doing for you in this project.

Development Server

This is an obvious one. You're developing, right? Well, you're in luck. Webpack is running a development server that defaults to port 8080. Visit http://localhost:8080, make changes to your JS or SCSS files, and watch Webpack refresh that screen.

Tree Shaking / Minification

Delivers super-sexy minified JavaScript without those dead branches! Your CSS is purged & minified as well. #Bandwidth

Babel / Polyfilling

Write ES6+ and beyond. Babel 7 is integrated and CNA is tweaked to support modern browsers. If you need to support older browsers, simply adjust the browserslist field in the package.json file. @babel/polyfill has been deprecated, but fear not! core-js to the rescue. Check it out at the top of entry.js.

Postcss

SCSS is included and get's compiled down to CSS. But that's half the magic. Postcss is autoprefixing our styles, smartly grouping media queries together, combining redudant selectors, removing comments, minifying color names, and sorting properties for better gzip compression! It's also purging unused css (see below).

Purgecss

Automatically removes unused CSS! It's only triggered when you run a build for production, so you can still hack away in Chrome's console and have access to all your styles. Also included is the purgecss-whitelister to prevent CSS from 3rd party tools being removed that you want to keep.

CleanWebpackPlugin

CleanWebpackPlugin is used to clean the dist folder when running a build. It's the folder that will contain your app's bundled assets.

MiniCssExtractPlugin

MiniCssExtractPlugin removes the CSS data that's in the JS bundle and extracts it into a CSS file. This is the recommended plugin to use instead of the old extract text webpack plugin.

HtmlWebpackPlugin

HtmlWebpackPlugin generates the index.html file. Dynamically creates a <style> tag in the <head> of the document and a <script> tag before the closing <body> tag, referencing the build assets.

Options

React Router

Option Alias Type Description Default
--router -r Boolean Includes React Router in your application, completely wired up & ready to go. Enjoy the widely supported go-to router of choice in the React ecosystem!

Examples:
--router
-r
false

Server - Express, MongoDB, API

If you're developing a fullstack app we've got you covered with Express and MongoDB. If you already have an existing server that you'd like to connect to - these options are for you too.

Option Alias Type Description Default
--express -e Boolean Set's up a Node server running Express.

Examples:
--express
-e
false
--api - String Sets the key value to devServer.proxy[api] in webpack.config.js. Used when you have a local back-end you'd like to proxy requests to while developing. For example, set this to /api if your backend responds to calls at /api/some-endpoint.

Examples:
--api /api
--api=/api
"/api"
--mongo -m Boolean Set's up MongoDB with a Node server running Express, all wired up & ready to go! If you use this option, no need to also use `--express`.

Examples:
--mongo
-m
false
--devServerPort - Number Port number to the webpack development server. You'll visit the app locally at http://localhost:<devServerPort>.
Note: apiPort takes priority over devServerPort. In the event they are both the same, devServerPort will automatically be adjusted.

Examples:
--devServerPort 1234
--devServerPort=1234
8080
--apiPort - Number Port number to the webpack development server. You'll visit the app locally at http://localhost:<devServerPort>.

Examples:
--devServerPort 1234
--devServerPort=1234
3000
--mongoPort --mp Number Port number that MongoDB connects on. If you haven't specifically set MongoDB's port when you installed it locally, simply leave this alone and use the default value.

Examples:
--mongoPort 30123
--mongoPort=30123
--mp 30123
--mp=30123
27017
--mongoPortProd --mpp Number Port number that MongoDB connects to in production. This value should be different than the default value when using MongoDB in production. It defaults to 27017 in case you didn't change the port in your production environment. But for security reasons, do yourself the favor and don't use the default value in production.

Examples:
--mongoPortProd 30123
--mongoPortProd=30123
--mpp 30123
--mpp=30123
27017
--mongoUser --mu String CNA is set up to to use authentication in production with MongoDB. This sets the user value. You will also need to set a user password, but there's no cli option. Nobody should type a password into a cli! The variable MONGO_USER_PASSWORD will be available in the .env file, but will not be set. Set it manually. See cna --mongoHelp for more information.

Examples:
--mongoUser mongo_master
--mongoUser=mongo_master
--mu mongo_master
--mu=mongo_master
-
--mongoAuthSource --mas String CNA is set up to to use authentication in production with MongoDB. This sets the database name for MongoDB to authenticate against. See cna --mongoHelp for more information.

Examples:
--mongoAuthSource admin
--mongoAuthSource=admin
--mas admin
--mas=admin
-

package.json options

Option Alias Type Description Default
--author - String Populates package.json field name of the same value. ''
--description - String Populates package.json field name of the same value. ''
--email - String Populates package.json field name of the same value. ''
--keywords - Array Populates package.json field name of the same value.
Example:
--keywords one two three
[]
--browserslist --bl Array Populates package.json field name of the same value. This field is used by @babel/preset-env and autoprefixer.The default value is aimed at supporting modern browsers only. Also, using last 2 versions might not do what you think. ['>0.25%', 'not ie 11', 'not op_mini all']
--repository --repo Array Populates package.json field name of the same value. ''

Information-only

Option Alias Description
--help -h Outputs the help screen, showing all the above documented options.
--mongoHelp --mh Outputs some helpful information about getting MongoDB prepared for production.
--version -v Outputs the version of CNA that you're using to the terminal.

Other options

Option Alias Type Description Default
--offline -o Boolean Forces npm to use cache when installing. Great if you don't want npm hogging your data. Tethering, anyone?

Examples:
--offline
-o
false
--force -f Boolean Want to install an app in a pre-existing folder? Use this. But be warned! There's a possibility you can overwrite files if the names conflict!

Examples:
--force
-f
false
--noGit - Boolean Don't want a git repo? This is for you. Keep in mind CNA won't initialize a git repo if the `--force` or `--repository` options are used.

Examples:
--noGit
false
--sandbox -s Boolean Creates a "sandbox" app which consists of 3 simple files:
  • index.html
  • styles.css
  • main.js
If you use this option, everything else will be ignored. This option is perfect for whipping up a quick directory with some files to play in.

Examples:
--sandbox
-s
false
--title -t String Sets the webpage title generated by Webpack's HtmlWebpackPlugin.

Examples:
--title 'JavaScript Rules'
--title='JavaScript Rules'
-t 'JavaScript Rules'
-t='JavaScript Rules'
Title-cased version of the app name.