@deephaven/code-studio

Quick Start

A few notes to get developers quickly up and running.

Running

In the application directory, run npm install to install dependencies, then use the following commands.

npm start

Start the project in development mode, open at http://localhost:3000. Page automatically updates when changes are saved.

npm run start-rewired

Start the project in development mode with experimental fast refresh enabled. Open at http://localhost:3000. Page should automatically refresh on changes while keeping state and not requiring you to login after each change.

npm test

Start continuous unit tests. We use Jest to run end-to-end tests. Tests will rerun on changed files, or you can change modes by pressing 'a' to run ALL tests continuously.

npm run test:e2e

Start the end-to-end testing UI. We use Cypress to run end-to-end tests. This defaults to testing http://localhost:3000, as specified in cypress.json. You should start your test server using npm start first. You can override these values in your own cypress.env.json file to point to a remote server if you wish.

To run a smoke test in headless mode, run npm run test:e2e:smoke. The current smoke test requires dashboards/workspace to already be created. In the future, we should refine the smoke tests to reset the database to an expected state before running the tests. More detail in Cypress Best Practices.

npm run build

Build a production build. Output goes to the ./build folder. Start up production server after build with serve -s build (may need to install serve first, with npm install -g serve)

npm run mock

Runs in development mode with the mock server. This overrides the REACT_APP_CORE_API_URL setting. See Mock API for details.

Project Settings

Project specific settings are stored in the .env file. There is also an .env.development file which is only loaded in development builds, and .env.development.local which is only for local builds. For local development, you should be modifying .env.development.local. For more information on .env, see https://create-react-app.dev/docs/adding-custom-environment-variables#adding-development-environment-variables-in-env Below are some of the common properties which are configurable in the .env file.

REACT_APP_CORE_API_URL

One common setup is to override the API server URL to point to another server. For example, add the following block to .env.development.local to have npm start point to a remote server for the API:

REACT_APP_CORE_API_URL=https://www.myserver.com/jsapi

REACT_APP_LOG_LEVEL

Printing detailed logs when debugging can be handy. To enable the highest level of logging, set the log level in your .env.development.local file:

REACT_APP_LOG_LEVEL=4

When running the unit tests, you often do not want any logs to be printed out. To disable the logs while running the unit tests, set the log level in your .env.test.local file:

REACT_APP_LOG_LEVEL=-1

See Log.js for different log levels.

REACT_APP_ENABLE_LOG_PROXY

Set to true or false

Turns on the logger proxy which captures log messages so users can easily export debug info for us. Enabling this will affect the line numbers shown in the console. Defaults to false in development and true in production.

In development, DHLogProxy and DHLogHistory are added to the window so they can be manipulated directly from the console if needed. DHLogProxy.enable() will capture and emit events for all logging events. DHLogHistory.enable() will attach event listeners to the DHLogProxy events. Both also have a disable method.

Development Environment

Visual Studio Code is recommended for code editing. We use some extensions to help our development:

• Prettier: Automatically formats code to our style. Enable the formatOnSave option to auto format when saving. Also set the Editor:Default Formatter to ebsenp.prettier-vscode
• ESLint: Identifies linting errors, gives options to fix them automatically.
• stylelint: Identifies scss lint errors.
• SCSS IntelliSense: Autocomplete for SCSS files
• Debugger for Chrome: Set up debugging in Chrome.

Use Chrome for debugging, install the React and Redux extensions.

• React Developer Tools: Allows inspection/changing the props/state of react components.
• Redux DevTools: Inspect the redux store data.

VSCode Typescript Version Settings

• Open a TS file. In the bottom right of VSCode you will see "Typescript #.#.#". Click on the version number > Select Typescript Version > Use Workspace Version. This ensures Intellisense matches the TS version and features we compile against.

Data Storage

There is the data for the current session stored in the local redux state (Redux Data), and data stored remotely in the workspaceData table in the WebClientData PQ on the server.

Redux Data

The application stores data locally for the current session using Redux. Take a look in the src/redux/reducers/index.js file for comments on the general structure and what's stored, and go into individual reducers to get the details about the data being stored.

You can also use the Chrome Redux DevTools to inspect live in a development or production environment: https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en

The state transitions are also logged in the browser developer console in develop builds.

Workspace Data

Data is stored remotely on the server in a Persistent Query named WebClientData, in one table workspaceData. Take a look at WorkspaceStorage.js for details on how it is stored.

Mock API

While developing, you may want to test specific cases that can be cumbersome to test against a real stack. You can run the mock API implementation in public/__mocks__/dh-core.js by executing npm run mock command. This mock is also used for unit tests. When new functions are added to the API, ideally stubs returning a generic success case should be added to the mock API as well to avoid breakage when running the mock.

Styleguide/Component Development

The styleguide uses Storybook and can be accessed using npm run storybook. This runs independently of the dev server. Storybook can be used to develop components in isolation. The styleguide displays many common components and how to use them. When creating a new component, it should be added to the styleguide to show usage using a component.stories.jsx file.

Legacy Style Guide

When running in development mode (npm run start), a style guide is served up at http://localhost:3000/styleguide. This is for legacy purposes now while everything is ported over to Storybook. Do NOT add new components to this styleguide, only use it for reference if things are missing in Storybook.

Architecture

At a high level, the Web UI uses the Iris API to communicate with the servers/workers necessary. For details on the Iris API,see the Web Developers Guide. For more details on the sockets and ports used, see Network Services and Web API in our docs.

graph TD
A[Web UI] -->B[Iris API]
B --> |Websocket| C[Web API Server]
B --> |Websockets| D[Query Workers]

Dashboards

The main layout of the app is based on Dashboards, which is essentially a top level tab the user has open. Before a Dashboard is loaded, it is simply a LazyDashboard. Once activated, it will load it's layout into Golden Layout. It's layout is composed of numerous Panels (see below). Each DashboardContainer listens for TabEvents from the higher level app, and for panel events emitted on the Golden Layout EventHub.

Panels

Each Dashboard is composed of panels. There are many different kinds of panels, such as IrisGridPanel, ChartPanel, MarkdownPanel, and ConsolePanel. Each panel should save a dehydrated state that can be serialized and saved in the database, then deserialized and hydrated when opening a dashboard. The dehydration/hydration step is defined in DashboardContainer with makeHydrateComponentPropsMap and dehydrateClosedComponentConfigMap.

Initial Project Setup

This project was bootstrapped with Create React App.

Learn More

You can learn more in the Create React App documentation.

To learn React, check out the React documentation.

Code Splitting

This section has moved here: https://facebook.github.io/create-react-app/docs/code-splitting

Analyzing the Bundle Size

This section has moved here: https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size

Making a Progressive Web App

This section has moved here: https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app

Advanced Configuration

This section has moved here: https://facebook.github.io/create-react-app/docs/advanced-configuration

Deployment

This section has moved here: https://facebook.github.io/create-react-app/docs/deployment

yarn build fails to minify

This section has moved here: https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify

Legal Notices

Deephaven Data Labs and any contributors grant you a license to the content of this repository under the Apache 2.0 License, see the LICENSE file.