Preparing the App for Packaging and Deployment

Researcher

  • Ensure the app code is structured appropriately.

Developer

Working within the app repository:

  • If the web app bundles external html, scripts, or strings:

    • npm install @rollup/plugin-html, rollup-plugin-string

  • Verify package.json is configured correctly, especially the "name" field.

    • ex. "name": "@bdelab/package-name"

  • Check both Webpack and Rollup configurations, changing any relevant fields including page title and app name where applicable.

  • Sample webpack.config.cjs from roar-swr:

    const path = require('path');
    const webpack = require('webpack');
    // eslint-disable-next-line import/no-extraneous-dependencies
    const { merge } = require('webpack-merge');
    // eslint-disable-next-line import/no-extraneous-dependencies
    const HtmlWebpackPlugin = require('html-webpack-plugin');
    const { sentryWebpackPlugin } = require('@sentry/webpack-plugin');
    const dotenv = require('dotenv');
    dotenv.config();
    
    const commonConfig = {
      optimization: {
        moduleIds: 'deterministic',
        runtimeChunk: 'single',
        splitChunks: {
          cacheGroups: {
            vendor: {
              test: /[\\/]node_modules[\\/]/,
              name(module) {
                // get the name. E.g. node_modules/packageName/not/this/part.js
                // or node_modules/packageName
                const packageName = module.context.match(/[\\/]node_modules[\\/](.*?)([\\/]|$)/)[1];
    
                // npm package names are URL-safe, but some servers don't like @ symbols
                return `npm.${packageName.replace('@', '')}`;
              },
              chunks: 'all',
            },
          },
        },
      },
      resolve: {
        fallback: {
          path: require.resolve('path-browserify'),
        },
      },
      module: {
        rules: [
          {
            test: /\.m?js/,
            resolve: {
              fullySpecified: false,
            },
          },
          {
            test: /\.scss$/i,
            use: ['style-loader', 'css-loader', 'sass-loader'],
          },
          {
            test: /\.(png|svg|jpg|jpeg|gif|webp)$/i,
            type: 'asset/resource',
            generator: {
              filename: 'img/[name][ext]',
            },
          },
          {
            test: /\.mp3$/,
            use: [
              {
                loader: 'file-loader',
                options: {
                  name: '[path][name].[ext]',
                  outputPath: 'audio',
                },
              },
            ],
          },
          {
            test: /\.mp4$/,
            use: [
              {
                loader: 'file-loader',
                options: {
                  name: '[name].[ext]',
                  outputPath: 'video',
                },
              },
            ],
          },
          {
            test: /\.csv$/,
            use: [
              {
                loader: 'csv-loader',
                options: {
                  header: true,
                  dynamicTyping: true,
                  skipEmptyLines: true,
                },
              },
            ],
          },
        ],
      },
      experiments: {
        topLevelAwait: true,
      },
    };
    
    const webConfig = merge(commonConfig, {
      entry: {
        index: path.resolve(__dirname, 'serve', 'serve.js'),
      },
      output: {
        filename: '[name].[contenthash].bundle.js',
        path: path.resolve(__dirname, 'dist'),
        clean: {
          keep: /\.git/,
        },
      },
      devtool: 'source-map',
      plugins: [
        new HtmlWebpackPlugin({
          title: 'Rapid Online Assessment of Reading - SWR',
        }),
        sentryWebpackPlugin({
          org: 'roar-89588e380',
          project: 'swr',
          authToken: process.env.SENTRY_AUTH_TOKEN,
          debug: true,
          errorHandler: (err) => {
            console.warn(err);
          },
        }),
      ],
    });
    
    const productionConfig = merge(webConfig, {
      mode: 'production',
    });
    
    const developmentConfig = merge(webConfig, {
      mode: 'development',
      devServer: {
        port: 8000,
        static: './dist',
        client: {
          overlay: false,
        },
      },
    });
    
    module.exports = async (env, args) => {
      const roarDB = env.dbmode === 'production' ? 'production' : 'development';
    
      const envDependentConfig = {
        plugins: [
          new webpack.ids.HashedModuleIdsPlugin(), // so that file hashes don't change unexpectedly
          new webpack.DefinePlugin({
            ROAR_DB: JSON.stringify(roarDB),
          }),
          new webpack.ProvidePlugin({
            process: 'process/browser',
          }),
        ],
      };
    
      switch (args.mode) {
        case 'development':
          return merge(developmentConfig, envDependentConfig);
        case 'production':
          return merge(productionConfig, envDependentConfig);
        default:
          throw new Error('No matching configuration was found!');
      }
    };

Sample rollup.config.js from roar-swr:

    import commonjs from '@rollup/plugin-commonjs';
    import postcss from 'rollup-plugin-postcss';
    import dsv from '@rollup/plugin-dsv';
    import json from '@rollup/plugin-json';
    import terser from '@rollup/plugin-terser';
    import { nodeResolve } from '@rollup/plugin-node-resolve';
    import { sentryRollupPlugin } from '@sentry/rollup-plugin';
    import 'dotenv/config';
    
    export default {
      input: 'src/index.js',
      plugins: [
        postcss({
          extract: 'resources/roar-swr.css',
        }),
        dsv(),
        json(),
        nodeResolve({
          preferBuiltins: true,
        }),
        terser(),
        commonjs(),
        sentryRollupPlugin({
          org: 'roar-89588e380',
          project: 'swr',
          authToken: process.env.SENTRY_AUTH_TOKEN,
        }),
      ],
      output: [
        {
          dir: 'lib',
          name: '@bdelab/roar-swr',
          entryFileNames: '[name].[hash].js',
          chunkFileNames: '[name].[hash].js',
          format: 'es',
          sourcemap: true,
        },
      ],
    };

Create Staging and Production Hosting Targets on gse-roar-assessment Project

From the gse-roar-assessment Firebase project, navigate to "Hosting" on the left hand side.

  1. Click "add another site" in the top right corner
  2. Name the hosting targets with the following convention:
    • [roar][roam][roav]-app-name
    • [roar][roam][roav]-app-name-staging
  3. For example, an app named "roar-word" would have the following hosting targets:
    • https://roar-word.web.app
    • https://roar-word-staging.web.app

Ensure firebaseConfig.js Points to the Correct Firebase Configs

serve/firebaseConfig.js:

/* eslint-disable import/prefer-default-export */
import { log } from '../src/experiment/config/logger';

/* eslint-disable import/prefer-default-export */
const devFirebaseConfig = {
  apiKey: 'AIzaSyCX9WR-j9yv1giYeFsMpbjj2G3p7jNHxIU',
  authDomain: 'gse-yeatmanlab.firebaseapp.com',
  projectId: 'gse-yeatmanlab',
  storageBucket: 'gse-yeatmanlab.appspot.com',
  messagingSenderId: '292331000426',
  appId: '1:292331000426:web:91a04220991e3405737013',
  measurementId: 'G-0TBTMDS993',
};

const productionFirebaseConfig = {
  apiKey: 'AIzaSyDw0TnTXbvRyoVo5_oa_muhXk9q7783k_g',
  authDomain: 'gse-roar-assessment.firebaseapp.com',
  projectId: 'gse-roar-assessment',
  storageBucket: 'gse-roar-assessment.appspot.com',
  messagingSenderId: '757277423033',
  appId: '1:757277423033:web:d6e204ee2dd1047cb77268',
};

export const firebaseConfig =
  // eslint-disable-next-line no-undef
  ROAR_DB === 'production' ? productionFirebaseConfig : devFirebaseConfig;

export const roarConfig = {
  firebaseConfig,
};

// eslint-disable-next-line operator-linebreak
const logMessage = `This ROAR app will write data to the ${roarConfig.firebaseConfig.projectId} firestore database`;
log.info(logMessage);`

Modify .firebaserc to deploy to the designated targets.

.firebaserc:

{
  "projects": {
    "default": "gse-roar-assessment"
  },
  "targets": {
    "gse-roar-assessment": {
      "hosting": {
        "production": [
          "[name of production target in gse-roar-assessment hosting]"
        ],
        "staging": [
          "[name of staging target in gse-roar-assessment hosting]"
        ],
      }
    }
  }
}

Set the Deployment Targets Using gcloud CLI:

  1. Install the Firebase CLI:

    npm install -g firebase-tools

  2. Add a default Firebase project:

    firebase use --add

  3. Select the project gse-roar-assessment

  4. Set the deployment targets:

    firebase target:apply hosting production [name of production target in gse-roar-assessment hosting]
firebase target:apply hosting staging [name of staging target in gse-roar-assessment hosting]

  5. Ensure that firebase.json targets are set to "production" and "staging"

firebase.json:

{
  "hosting": [
    {
      "public": "dist",
      "target": "production",
      "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
      "rewrites": [
        {
          "source": "**",
          "destination": "/index.html"
        }
      ],
      "headers": [
        {
          "source": "**/*",
          "headers": [
            {
              "key": "Feature-Policy",
              "value": "autoplay=*"
            }
          ]
        }
      ]
    },
    {
      "public": "dist",
      "target": "staging",
      "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
      "rewrites": [
        {
          "source": "**",
          "destination": "/index.html"
        }
      ],
      "headers": [
        {
          "source": "**/*",
          "headers": [
            {
              "key": "Feature-Policy",
              "value": "autoplay=*"
            }
          ]
        }
      ]
    }
  ]
}

Service Account Key for Firebase Deployment

Each app will need a Firebase service account .json file to deploy to Firebase. The Firebase service account authorizes the app to access Firebase services using a set of credentials. The service account key is a JSON file that contains the necessary credentials to authenticate the app with Firebase services. This file should be stored in the GitHub repository action secrets.

To create a service account key:

  1. Navigate to the Firebase console and select the "gse-roar-assessment" project.
  2. Click on the gear icon in the top left corner and select "Project settings".
  3. Navigate to the "Service accounts" tab.
  4. Click on "Generate new private key".
  5. Save the JSON file to the local machine (you may need it for additional Firebase actions).
  6. Copy/paste the entire JSON file to the GitHub repository secrets as FIREBASE_SERVICE_ACCOUNT_GSE_ROAR_ASSESSMENT.

Setup Automated Workflows

GitHub actions ensure a consistent deployment environment where automated testing and monitoring are able to catch any new or regressive bugs that might have occurred in development.

  1. Create a new directory at the root of the project to hold the workflow files
    • ~/.github/workflows
  2. Add the pull request template into the .github/ directory
    • PULL_REQUEST_TEMPLATE.md: 
      •   ## Proposed changes

 <!--
 Describe your changes here. Why are they necessary?

 If it fixes a bug or resolves a feature request, be sure to link to that issue.

 If appropriate, include images of the expected behavior or user experience.
 You can drag and drop images into this text box.
 -->

 ## Types of changes

 What types of changes does this pull request introduce?

 <!-- Put an `x` in the boxes that apply -->

 - [ ] Bugfix (non-breaking change which fixes an issue)
   - [ ] New feature (non-breaking change which adds functionality)
   - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
   - [ ] Refactoring (non-breaking change that does not add functionality but makes code cleaner or more efficient)
   - [ ] Documentation Update
   - [ ] Tests (new or updated tests)
   - [ ] Style (changes to code styling)
   - [ ] CI (continuous integration changes)
   - [ ] Repository Maintenance
   - [ ] Other (please describe below)

 ## Checklist

 <!--
 Put an `x` in the boxes that apply. You can also fill these out after creating
 the PR. If you're unsure about any of them, don't hesitate to ask.  We're here
 to help! This is simply a reminder of what we are going to look for before
 merging your code.
 -->

 - [ ] I have read the [guidelines for contributing](https://github.com/yeatmanlab/roar-dashboard/blob/main/.github/CONTRIBUTING.md).
   - [ ] The changes in this PR are as small as they can be. They represent one and only one fix or enhancement.
   - [ ] Linting checks pass with my changes.
   - [ ] Any existing unit tests pass with my changes.
   - [ ] Any existing end-to-end tests pass with my changes.
   - [ ] I have added tests that prove my fix is effective or that my feature works.
   - [ ] If this PR fixes an existing issue, I have added a unit or end-to-end test that will detect if this issue reoccurs.
   - [ ] I have added JSDoc comments as appropriate.
   - [ ] I have added the necessary documentation to the [roar-docs repository](https://github.com/yeatmanlab/roar-docs).
   - [ ] I have shared this PR on the roar-pr-reviews channel (if I have access)
   - [ ] I have linked relevant issues (if any)

 ## Justification of missing checklist items

 <!--
 If you feel that a checklist item above is not applicable to this PR, please
 provide your justification here. Otherwise, delete this section.
 -->

 ## Further comments

 <!--
 If this is a relatively large or complex change, kick off the discussion by
 explaining why you chose the solution you did and what alternatives you
 considered, etc...
 -->
  3. Copy the following GitHub workflow files into the workflows folder (we will create and add the necessary secrets to the GitHub repo in a later step)

    • firebase-hosting-merge.yml:

      •    name: Deploy to Staging Firebase Hosting on Merge
   'on':
     push:
       branches:
         - main
       tags-ignore:
         - 'v[0-9]+.[0-9]+.[0-9]+'
         - 'v[0-9]+.[0-9]+.[0-9]+-alpha.[0-9]+'
         - 'v[0-9]+.[0-9]+.[0-9]+-beta.[0-9]+'
   jobs:
     build_and_deploy:
       if: "!contains(github.event.head_commit.message, '[skip ci]')"
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
         - run: 'npm ci && npm run build:prod'
         - uses: FirebaseExtended/action-hosting-deploy@v0
           with:
             repoToken: '${{ secrets.GITHUB_TOKEN }}'
             firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_GSE_ROAR_ASSESSMENT }}'
             channelId: live
             projectId: gse-roar-assessment
             target: staging

    • deploy-firebase-test-cypress.yml:

      •   name: Firebase Deploy to Staging and Cypress e2e Tests
  on:
    pull_request:
      types: [opened, reopened, synchronize]

  concurrency:
    group: ci-preview-tests-${{ github.ref }}-1
    cancel-in-progress: true

  jobs:
    build_and_preview:
      if: '${{ github.event.pull_request.head.repo.full_name == github.repository }}'
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - uses: actions/setup-node@v4
          with:
            node-version: 'lts/*'
        - run: npm ci && npm run build:dev
        - name: Deploy to Firebase Hosting Channel
          id: firebase-deploy
          uses: FirebaseExtended/action-hosting-deploy@v0
          with:
            repoToken: '${{ secrets.GITHUB_TOKEN }}'
            firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_GSE_ROAR_ASSESSMENT }}'
            projectId: gse-roar-assessment
            target: staging
        - run: echo ${{ fromJson(steps.firebase-deploy.outputs.urls)[0] }}
      outputs:
        deployUrl: ${{ fromJson(steps.firebase-deploy.outputs.urls)[0] }}

    cypress_run:
      needs: [build_and_preview]
      runs-on: ubuntu-latest
      timeout-minutes: 60
      strategy:
        fail-fast: false
        matrix:
          browser: [chromium, edge]
          containers: [1, 2]
      env:
        CYPRESS_BASE_URL: ${{ needs.build_and_preview.outputs.deployUrl }}
        CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}
        COMMIT_INFO_MESSAGE: Tests for PR ${{ github.event.number }} "${{ github.event.pull_request.title }}" from commit "${{ github.event.pull_request.head.sha }}"
        COMMIT_INFO_SHA: ${{ github.event.pull_request.head.sha }}
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      steps:
        - name: Checkout
          uses: actions/checkout@v4
        - name: Cypress run
          uses: cypress-io/github-action@v6
          with:
            browser: ${{ matrix.browser }}
            headed: true
            build: echo "Build step already completed"
            start: echo "App already deployed to Firebase"
            wait-on: ${{ env.CYPRESS_BASE_URL }}
            wait-on-timeout: 60
            record: true
            parallel: true
            spec: 'cypress/e2e/**/*'
            ci-build-id: ${{ github.run_id }}-${{ matrix.browser }}

    • publish-to-npm-create-new-release.yml:

      •  name: Publish, Release, and Deploy
 on:
  push:
   tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'
      - 'v[0-9]+.[0-9]+.[0-9]+-alpha.[0-9]+'
      - 'v[0-9]+.[0-9]+.[0-9]+-beta.[0-9]+'
 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout 🛎️
         uses: actions/checkout@v3
         with:
           ref: main
     
       - name: Setup Node.js environment
         uses: actions/setup-node@v3
         with:
           node-version: 'lts/*'
           registry-url: 'https://registry.npmjs.org'
           node-version-file: '.nvmrc'
           cache: 'npm'
     
       - name: Cache dependencies
         uses: actions/cache@v3
         with:
           path: ~/.npm
           key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
           restore-keys: |
             ${{ runner.os }}-node-
     
       - name: Install and Build 🔧
         run: |
           npm ci
           npm run package
     
       - name: Check for uncommitted changes
         run: |
           git config --local user.email "action@github.com"
           git config --local user.name "GitHub Action"
           git commit -am "Commit uncommitted changes [skip ci]"
     
       - name: Push tag
         run: |
           git push origin main --follow-tags
     
       - name: Publish 🚀
         run: npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
     
       - name: Create GitHub Release
         id: create_release
         uses: actions/create-release@v1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           tag_name: ${{ github.ref }}
           release_name: Release ${{ github.ref }}
           draft: false
           prerelease: false
     
       - name: Create Sentry release and upload source maps
         uses: getsentry/action-release@v1.7.0
         env:
           SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
           SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
           SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }}
         with:
           environment: production
           sourcemap: ./lib/*.js.map
           version: ${{ github.ref }}
     
       - name: Notify on failure
         if: failure()
         uses: actions/github-script@v5
         with:
           script: |
             const issue = {
               owner: context.repo.owner,
               repo: context.repo.repo,
               title: "Combined workflow failed",
               body: `The workflow failed on [${context.sha.substring(0, 7)}](${context.payload.repository.html_url}/commit/${context.sha}). Please check it.`,
             };
             github.rest.issues.create(issue);
        
   deploy_to_production:
     needs: build
     runs-on: ubuntu-latest
     steps:
      - uses: actions/checkout@v3
      - run: 'npm ci && npm run build:prod'
      - uses: FirebaseExtended/action-hosting-deploy@v0
        with:
           repoToken: '${{ secrets.GITHUB_TOKEN }}'
           firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_GSE_ROAR_ASSESSMENT }}'
           channelId: live
           projectId: gse-roar-assessment
           target: production
                     
      - name: Notify on Failure
        if: failure()
        uses: actions/github-script@v5
        with:
         script: |
           const issue = {
           owner: context.repo.owner,
           repo: context.repo.repo,
           title: "Combined workflow failed",
           body: `The workflow failed on [${context.sha.substring(0, 7)}](${context.payload.repository.html_url}/commit/${context.sha}). Please check it.`,
           };
           github.rest.issues.create(issue);

    • submit-dashboard-pr.yml:

      •  name: Update dependency version in ROAR-dashboard
 
 on:
   workflow_run:
     workflows: ['Publish, Release, and Deploy']
     types:
       - completed
 
 jobs:
   update-version:
     runs-on: ubuntu-latest
 
     if: ${{ github.event.workflow_run.conclusion == 'success' }}
 
     steps:
       - name: Checkout the repository
         uses: actions/checkout@v2
 
       - name: Get the new version
         id: get_new_version
         run: |
           VERSION=$(jq -r '.version' package.json)
           echo "NEW_VERSION=$VERSION" >> $GITHUB_OUTPUT
 
       - name: Checkout the target repository
         uses: actions/checkout@v2
         with:
           repository: yeatmanlab/roar-dashboard
           token: ${{ secrets.DASHBOARD_REPO_TOKEN }}
           path: dashboard-repo
 
       - name: Update version in package.json
         run: |
           cd dashboard-repo
           NEW_VERSION=${{ steps.get_new_version.outputs.NEW_VERSION }}
           jq --arg ver "$NEW_VERSION" '.dependencies["@bdelab/roar-swr"] = $ver' package.json > temp.json && mv temp.json package.json
           npm i
 
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v4
         with:
           path: dashboard-repo
           token: ${{ secrets.DASHBOARD_REPO_TOKEN }}
           commit-message: Update SWR version to ${{ steps.get_new_version.outputs.NEW_VERSION }}
           branch: dep/update-swr-${{ steps.get_new_version.outputs.NEW_VERSION }}
           base: main
           title: Update SWR version to ${{ steps.get_new_version.outputs.NEW_VERSION }}
           body: |
             This PR updates the version of `@bdelab/roar-swr` to ${{ steps.get_new_version.outputs.NEW_VERSION }}.