🔥🔥 Flame scripts 🔥🔥 frontend mafia

Usage 🚀

yarn add dbz-flame-scripts

Development usage

# to be able to link the package
cd dbz-flame-scripts
yarn link

# to use the local package within your app instead of npm’s version
cd app
yarn link dbz-flame-scripts # to use local linked dbz-flame-scripts
yarn unlink dbz-flame-script # to use package.json’s version

Commands 🎮

build [options]  Creates application bundles with Webpack to the /build folder

package.json:
  specify a custom webpack configuration in flame.webpackConfig
  webpack-merge will combine that with the base webpack configuration

[options]
  --no-ssr
  --debug
  --verbose
  --analyze, --analyse
  --colors
  --webpackConfig

start [options]  Launches app using BrowserSync in Webpack watch mode

package.json:
  specify a custom launch url in: flame.startPath
  specify a custom webpack configuration in flame.webpackConfig
  webpack-merge will combine that with the base webpack configuration

env.ini
  takes HOST and PORT and to launch the server with

[options]
  --webpackConfig

deploy <env>     Deploy app to environment

Under the hood:
  git commit --amend --no-edit
  created and pushes a tag "dbz_{branch}_release_{env}_{timestamp}"

<env>:
  pw
  tech
  cc
  red
  bid
  pro
  space
  prod|production

vault <env>      Fetches environment variables from vault and writes it into
a .env file in the projects directory.

package.json:
  specify the vault app name in: flame.vaultAppName

<env>:
  pw
  tech
  cc
  red
  bid
  pro
  space
  production

syncS3 <env>     Deploy app’s build/public folder to aws s3

package.json:
  specify the aws s3 path in: flame.awsS3Path

<env>:
  pw
  tech
  cc
  red
  bid
  pro
  space
  production

test [options]   Tests app using Jest

package.json:
  the jest section will be merged with the base jest configuration

[options]
  -w, --watch
  --color

Devs: to keep this up-to-date, after updating the descriptions for a command, copy/paste the output of flame-scripts --help here.

flame section in package.json

{
  "flame": {
    // For some repo’s we don’t want to open up the browser displaying a 404 page
    // startPath will specify the path to launch the browser in when running the
    // command: flame-scripts start
    "startPath": "/en/property-for-rent/residential/", // Optional

    // vault paths look like this:
    // secret/beta/dashboard-frontend/dashboard-frontend-beta-pw
    // once we run the command: "flame-scripts vault pw", we can figure out
    // the environment from the arguments, but we will still need to know the
    // app name, which is why we need a specified vaultAppName:
    // `secret/beta/${vaultAppName}/${vaultAppName}-beta-${env}`
    "vaultAppName": "property-lpv-desktop", // Required

    // aws s3 paths look like this:
    // s3://dbz-pw-static/property/desktop/latest
    // once we run the command: "flame-scripts syncS3 pw", we will push the
    // build/public/ folder to the correct s3 bucket + specified path
    // `dbz-${env}-static/${awsS3Path}`
    "awsS3Path": "property/desktop/latest", // Required

    // The specified webpack config will be merged using webpack smart merge:
    // https://github.com/survivejs/webpack-merge
    // we check whether its exporting a single object (only client build) or an
    // array of client and server configs. In the latter case the first config is
    // always the client build and the second the server. in case you need to do
    // conditional checks, make sure to check how its done in the base configs
    // (configs/webpack.config.js) and that you do it consistently in the same
    // manner.
    "webpackConfig": "config/webpack.config.js", // Optional

    // This is to specify whether we should start/build with a server side build
    // alternatively you can use the flag --no-ssr in the same commands to disable
    // the server bundle.
    "webpackServer": true, // Optional

    // proxy option while running the command flame-scripts start
    // https://webpack.js.org/configuration/dev-server/#devserver-proxy
    // Optional
    "webpackDevServerProxy": {
      "/api": {
        "target": "https://dubai.dubizzle.space",
        "pathRewrite": {
          "^/api": "",
          "url=http://localhost:5050/api": "url=https://dubai.dubizzle.space"
        },
        "secure": false
      }
    }
  }
}

How does it work?

The entry file is bin/flame-scripts. It’s internally using commander to build the CLI: https://github.com/tj/commander.js/, it sets the package.json config and registers the commands from commands/index.js. The scripts are originally taken from: https://github.com/kriasoft/react-starter-kit/tree/master/tools as it seems to be the most complete webpack server-side-rending solution out there.

Config

The first thing we do for each command is get the project’s package.json and get the flame and jest configs. We can then use this data inside our scripts like so:

const config = require('configs/flame.config');

// the flame section in the package.json will be set directly to the config object
const awsPath = config.awsS3Path;

// whereas the jest config will be set to the jest key
const jest = config.jest;

// additionally we set the projectDir, since we will need to be able to access it later on
const projectDir = config.projectDir;

Commands

Commands can be added by creating a file in the commands/ folder and by adding it to the commands/index.js. Inside the bin file we loop over them as seen below:

// bin/flame-scripts
const commands = require('../commands');
commands.forEach(command => command(program));

Conventions

Descriptions should be listed at the top for readabilty and any checks should happen before we run the script. We probably could write run(require('../scripts/deploy'), env) in a better way, but this way it works with the current implementation of react-starter-kit’s run() script.

// commands/deploy.js
const description = `Deploy app to environment

Under the hood:
  git commit --amend --no-edit
  created and pushes a tag "dbz_{branch}_release_{env}_{timestamp}"

<env>:
  ${environments.join('\n  ')}
`;

function deploy(program) {
  program
    .command('deploy <env>')
    .description(description)
    .action(() => {
      /* eslint-disable global-require, no-console */
      const env = process.argv[3];

      if (!environments.includes(env)) {
        console.log(`Invalid deploy environment "${env}"

Valid options:
  ${environments.join('\n  ')}`);
        process.exit(1);
      }

      run(require('../scripts/deploy'), env).catch(err => {
        console.error(err.stack);
        process.exit(1);
      });
    });
}

Environments

To keep a central place for all the environments, we have a single config for it in configs/environments.js. The commands deploy vault syncS3 are all referencing this.

Issues encountered

If a command is not able to run, it’s likely due to the fact that some dependency is trying to run the version of your project’s dependency. Generally, you can simply remove that dependency and it should work.

If the project has the dependency react-scripts, the command test will not work properly.

Build/start issues related to:

[acorn, chalk]

Can be resolve by reinstalling webpack to flame-scripts: yarn remove webpack && yarn add webpack

Babel config

Remove any babel configs (.babelrc) from your project’s directory, otherwise it will get picked up instead by babel and/or jest. We are using a central babel.config.js in the configs folder.