Skip to content

DEVELOPER.md

Latest commit

 

History

History
185 lines (123 loc) · 7.46 KB

DEVELOPER.md

File metadata and controls

185 lines (123 loc) · 7.46 KB

Developer

This document describes how to set up your development environment to build and develop plandev-ui.

Prerequisite Knowledge

Before getting started with developing in this repository read/watch all of the following resources:

  1. Rich Harris - Rethinking Reactivity
  2. Svelte Tutorial
  3. Svelte Kit Documentation
  4. TailwindCSS Documentation

Prerequisite Software

Before you can run plandev-ui you must install and configure the following products on your development machine:

  • Git and/or the GitHub app; GitHub's Guide to Installing Git is a good source of information.

  • Node.js LTS which is used to run a development web server, and generate distributable files. We recommend using the Node Version Manager (NVM) to install Node.js and NPM on your machine. Once you have NVM installed you can use the required Node.js/NPM versions via:

    cd plandev-ui
nvm use

    Note: Ensure that you have your shell loading your profile settings (e.g. .bashrc_profile, .profile, etc), otherwise the VSCode tasks won't be starting the terminal up with the correct settings

  • OpenJDK Temurin LTS which is used to build the Java-based PlanDev services. If you're on OSX you can use brew:

    brew tap homebrew/cask-versions
brew install --cask temurin19

    Make sure you update your JAVA_HOME environment variable. For example with Zsh you can set your .zshrc to:

    export JAVA_HOME="/Library/Java/JavaVirtualMachines/temurin-19.jdk/Contents/Home"

  • Docker which is used to run the PlanDev services.

  • PlanDev which contains the main backend services. You can use the following commands to download, build, and run PlanDev:

    (NOTE: For compatibility with VSCode tasks, ensure that both PlanDev UI and PlanDev repos share the same parent directory and that NVM is installed for node version management)

    git clone https://github.com/NASA-AMMOS/plandev.git
cd plandev
cp .env.template .env

    Fill out the .env file with the following default environment variables:

    AERIE_PASSWORD=aerie
AERIE_USERNAME=aerie
HASURA_GRAPHQL_ADMIN_SECRET=aerie
HASURA_GRAPHQL_JWT_SECRET='{ "type": "HS256", "key": "oursupersecretsupersecurekey1234567890" }'
POSTGRES_PASSWORD=postgres
POSTGRES_USER=postgres

    Next build PlanDev, and start the services via Docker:

    Via VSCode tasks: (refer to to the development section)

    • Run the Build PlanDev task to build PlanDev
    • Run the PlanDev Containers task, to bring up all the containers

    Via CLI:

    ./gradlew assemble

# Notice we exclude the aerie_ui since we run it locally (i.e. not in Docker) for development.
docker-compose up --build --detach aerie_gateway aerie_merlin aerie_scheduler aerie_merlin_worker_1 aerie_merlin_worker_2 aerie_scheduler_worker_1 aerie_scheduler_worker_2 aerie_sequencing hasura postgres

    To stop and clean the PlanDev services:

    Via VSCode task:

    Run the Clean PlanDev task

    cd plandev
docker-compose down
docker rmi aerie_merlin aerie_scheduler aerie_merlin_worker_1 aerie_merlin_worker_2 aerie_scheduler_worker_1 aerie_scheduler_worker_2 aerie_sequencing
docker volume prune --force
./gradlew clean

    You should stop and clean the PlanDev services after each use (e.g. at the end of the day), or right after pulling down the latest changes.

Code Editor

The recommended editor for developing plandev-ui is VS Code with the following settings and extensions. You can easily use another editor of your choice as long as you can replicate the code formatting settings.

Settings.json

Your editor should follow the same settings found in .vscode/settings.json.

Extensions

  1. Svelte for VS Code
  2. Prettier - Code formatter
  3. ESLint
  4. Stylelint
  5. EditorConfig for VS Code
  6. GraphQL
  7. Path Intellisense
  8. Code Spell Checker
  9. Task Explorer

Getting the Sources

Clone the plandev-ui repository:

git clone https://github.com/NASA-AMMOS/plandev-ui.git
cd plandev-ui

Installing NPM Modules

Install the JavaScript modules needed to build plandev-ui:

npm install

Development

Via VSCode task:

Run the Development task to start everything including the PlanDev containers.

The Development task runs the following tasks:

  • PlanDev UI
  • PlanDev Backend
  • Svelte Check
  • Unit Tests

Via CLI:

Run npm run dev for a dev server. Navigate to http://localhost:3000/. The app will automatically reload if you change any of the source files. Since we have observed some issues using monaco-editor with the dev server on Firefox, we recommend using Chrome for development.

Building For Production

Via VSCode task:

Run the UI Build task

Via CLI:

Run npm run build to build a production version of the project. The build artifacts will be stored in the build/ directory.

Cleaning

Run the following commands to clean dependencies and build artifacts of plandev-ui. To be safe you should do this anytime you pull down the latest changes.

cd plandev-ui
rm -rf node_modules
rm -rf .svelte-kit
rm -rf build

After cleaning you can re-install NPM modules and start development.

Styling

PlanDev UI uses TailwindCSS version 3 as its CSS styling solution. TailwindCSS is a CSS framework that provides dynamic utility classes that increase consistency and themability in the UI. TailwindCSS classes are preferred over semantic class names in PlanDev UI (this is an ongoing process). If semantic class names are needed for a particular case, it is recommended that you use a tailwind @apply directive to include the tailwind classes within the semantic class instead of writing vanilla CSS so that all of the themeing variables are properly included.
⚡