Skip to content

Commit

Permalink
docs: reword and cleanup docs for local dev server (#11869)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ktmud
ktmud authored Jan 11, 2021
1 parent 23263da commit ff7b789
Show file tree
Hide file tree
Showing 2 changed files with 115 additions and 112 deletions.
225 changes: 114 additions & 111 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,11 +50,13 @@ little bit helps, and credit will always be given.
- [Flask server](#flask-server)
- [OS Dependencies](#os-dependencies)
- [Logging to the browser console](#logging-to-the-browser-console)
- [Frontend Assets](#frontend-assets)
- [nvm and node](#nvm-and-node)
- [Frontend](#frontend)
- [Prerequisite](#prerequisite)
- [Installing Dependencies](#installing-dependencies)
- [Building](#building)
- [nvm and node](#nvm-and-node)
- [Install dependencies](#install-dependencies)
- [Build assets](#build-assets)
- [Webpack dev server](#webpack-dev-server)
- [Other npm commands](#other-npm-commands)
- [Docker (docker-compose)](#docker-docker-compose)
- [Updating NPM packages](#updating-npm-packages)
- [Feature flags](#feature-flags)
Expand Down Expand Up @@ -198,6 +200,7 @@ Finally, never submit a PR that will put master branch in broken state. If the P

- Fill in all sections of the PR template.
- Title the PR with one of the following semantic prefixes (inspired by [Karma](http://karma-runner.github.io/0.10/dev/git-commit-msg.html])):

- `feat` (new feature)
- `fix` (bug fix)
- `docs` (changes to the documentation)
Expand Down Expand Up @@ -404,11 +407,13 @@ app.logger.error('An exception occurred!')
app.logger.info(form_data)
```

### Frontend Assets
### Frontend

Frontend assets (TypeScript, JavaScript, CSS, and images) must be compiled in order to properly display the web UI. The `superset-frontend` directory contains all NPM-managed frontend assets. Note that for some legacy pages there are additional frontend assets bundled with Flask-Appbuilder (e.g. jQuery and bootstrap). These are not managed by NPM and may be phased out in the future.

Frontend assets (TypeScript, JavaScript, CSS, and images) must be compiled in order to properly display the web UI. The `superset-frontend` directory contains all NPM-managed front end assets. Note that there are additional frontend assets bundled with Flask-Appbuilder (e.g. jQuery and bootstrap); these are not managed by NPM, and may be phased out in the future.
#### Prerequisite

#### nvm and node
##### nvm and node

First, be sure you are using recent versions of NodeJS and npm. We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage your node environment:

Expand All @@ -422,11 +427,9 @@ nvm use

For those interested, you may also try out [avn](https://github.com/nvm-sh/nvm#deeper-shell-integration) to automatically switch to the node version that is required to run Superset frontend.

#### Prerequisite

#### Installing Dependencies
#### Install dependencies

Install third-party dependencies listed in `package.json`:
Install third-party dependencies listed in `package.json` via:

```bash
# From the root of the repository
Expand All @@ -436,40 +439,40 @@ cd superset-frontend
npm ci
```

#### Building
#### Build assets

There are three types of assets you can build:

1. `npm run build`: the production assets, CSS/JSS minified and optimized
2. `npm run dev-server`: local development assets, with sourcemaps and hot refresh support
3. `npm run build-instrumented`: instrumented application code for collecting code coverage from Cypress tests

#### Webpack dev server

You can run the Webpack dev server (in a separate terminal from Flask), which runs on port 9000 and proxies non-asset requests to the Flask server on port 8088. After pointing your browser to `http://localhost:9000`, updates to asset sources will be reflected in-browser without a refresh.
The dev server by default starts at `http://localhost:9000` and proxies the backend requests to `http://localhost:8080`. It's possible to change these settings:

```bash
# Run the dev server
# Start the dev server at http://localhost:9000
npm run dev-server

# Run the dev server on a non-default port
npm run dev-server -- --devserverPort=9001

# Run the dev server proxying to a Flask server on a non-default port
# Proxy backend requests to a Flask server running on a non-default port
npm run dev-server -- --supersetPort=8081

# Or proxy it to a remote backend so you can test frontend changes without
# starting the backend locally
# Proxy to a remote backend but serve local assets
npm run dev-server -- --superset=https://superset-dev.example.com
```

Alternatively you can use one of the following commands.
The `--superset=` option is useful in case you want to debug a production issue or have to setup Superset behind a firewall. It allows you to run Flask server in another environment while keep assets building locally for the best developer experience.

```bash
# Start a watcher that recompiles your assets as you modify them (but have to manually reload your browser to see changes.)
npm run dev
#### Other npm commands

# Compile the TypeScript/JavaScript and CSS in production/optimized mode for official releases
npm run prod
```
Alternatively, there are other NPM commands you may find useful:

If you run this service from somewhere other than your local machine, you may need to add hostname value to webpack.config.js at .devServer.public specifying the endpoint at which you will access the app. For example: myhost:9001. For convenience you may want to install webpack, webpack-cli and webpack-dev-server globally so that you can run them directly:

```bash
npm install --global webpack webpack-cli webpack-dev-server
```
1. `npm run build-dev`: build assets in development mode.
2. `npm run dev`: built dev assets in watch mode, will automatically rebuild when a file changes

#### Docker (docker-compose)

Expand All @@ -495,7 +498,7 @@ If you want to use the same flag in the client code, also add it to the FeatureF

```typescript
export enum FeatureFlag {
SCOPED_FILTER = 'SCOPED_FILTER',
SCOPED_FILTER = "SCOPED_FILTER",
}
```

Expand Down Expand Up @@ -726,7 +729,7 @@ In TypeScript/JavaScript, the technique is similar:
we import `t` (simple translation), `tn` (translation containing a number).

```javascript
import { t, tn } from '@superset-ui/translation';
import { t, tn } from "@superset-ui/translation";
```

### Enabling language selection
Expand Down Expand Up @@ -831,23 +834,23 @@ When `superset-ui` packages are linked with `npm link`, the dev server will auto

Note that every time you do `npm install`, you will lose the symlink(s) and may have to run `npm link` again.


### Visualization Plugins

The topic of authoring new plugins, whether you'd like to contribute
it back or not has been well documented in the
[So, You Want to Build a Superset Viz Plugin...](https://preset.io/blog/2020-07-02-hello-world/) blog post

To contribute a plugin to Superset-UI, your plugin must meet the following criteria:
* The plugin should be applicable to the community at large, not a particularly specialized use case
* The plugin should be written with TypeScript
* The plugin should contain sufficient unit/e2e tests
* The plugin should use appropriate namespacing, e.g. a folder name of `plugin-chart-whatever` and a package name of `@superset-ui/plugin-chart-whatever`
* The plugin should use them variables via Emotion, as passed in by the ThemeProvider
* The plugin should provide adequate error handling (no data returned, malformatted data, invalid controls, etc.)
* The plugin should contain documentation in the form of a populated `README.md` file
* The plugin should have a meaningful and unique icon
* Above all else, the plugin should come with a *commitment to maintenance* from the original author(s)

- The plugin should be applicable to the community at large, not a particularly specialized use case
- The plugin should be written with TypeScript
- The plugin should contain sufficient unit/e2e tests
- The plugin should use appropriate namespacing, e.g. a folder name of `plugin-chart-whatever` and a package name of `@superset-ui/plugin-chart-whatever`
- The plugin should use them variables via Emotion, as passed in by the ThemeProvider
- The plugin should provide adequate error handling (no data returned, malformatted data, invalid controls, etc.)
- The plugin should contain documentation in the form of a populated `README.md` file
- The plugin should have a meaningful and unique icon
- Above all else, the plugin should come with a _commitment to maintenance_ from the original author(s)

Submissions will be considered for submission (or removal) on a case-by-case basis.

Expand Down Expand Up @@ -990,22 +993,22 @@ Note not all fields are correctly catagorized. The fields vary based on visualiz

### Time

| Field | Type | Notes |
| ---------------------- | --------------- | ------------------------------------- |
| `druid_time_origin` | _string_ | The Druid **Origin** widget |
| `granularity` | _string_ | The Druid **Time Granularity** widget |
| `granularity_sqla` | _string_ | The SQLA **Time Column** widget |
| `time_grain_sqla` | _string_ | The SQLA **Time Grain** widget |
| `time_range` | _string_ | The **Time range** widget |
| Field | Type | Notes |
| ------------------- | -------- | ------------------------------------- |
| `druid_time_origin` | _string_ | The Druid **Origin** widget |
| `granularity` | _string_ | The Druid **Time Granularity** widget |
| `granularity_sqla` | _string_ | The SQLA **Time Column** widget |
| `time_grain_sqla` | _string_ | The SQLA **Time Grain** widget |
| `time_range` | _string_ | The **Time range** widget |

### GROUP BY

| Field | Type | Notes |
| ------------------------- | --------------- | --------------------------- |
| `metrics` | _array(string)_ | See Query section |
| `order_asc` | - | See Query section |
| `row_limit` | - | See Query section |
| `timeseries_limit_metric` | - | See Query section |
| Field | Type | Notes |
| ------------------------- | --------------- | ----------------- |
| `metrics` | _array(string)_ | See Query section |
| `order_asc` | - | See Query section |
| `row_limit` | - | See Query section |
| `timeseries_limit_metric` | - | See Query section |

### NOT GROUPED BY

Expand All @@ -1023,9 +1026,9 @@ Note not all fields are correctly catagorized. The fields vary based on visualiz

### Y Axis 2

| Field | Type | Notes |
| ----------------- | -------- | --------------------------------------------------- |
| `metric_2` | - | The **Right Axis Metric** widget. See Query section |
| Field | Type | Notes |
| ---------- | ---- | --------------------------------------------------- |
| `metric_2` | - | The **Right Axis Metric** widget. See Query section |

### Query

Expand All @@ -1044,68 +1047,68 @@ The `metric` (or equivalent) and `timeseries_limit_metric` fields are all compos

### Chart Options

| Field | Type | Notes |
| --------------------- | --------- | ------------------------------------------------ |
| `color_picker` | _object_ | The **Fixed Color** widget |
| `label_colors` | _object_ | The **Color Scheme** widget |
| `normalized` | _boolean_ | The **Normalized** widget |
| Field | Type | Notes |
| -------------- | --------- | --------------------------- |
| `color_picker` | _object_ | The **Fixed Color** widget |
| `label_colors` | _object_ | The **Color Scheme** widget |
| `normalized` | _boolean_ | The **Normalized** widget |

### Y Axis

| Field | Type | Notes |
| ------------------- | --------------- | ---------------------------- |
| `y_axis_2_label` | _N/A_ | _Deprecated?_ |
| `y_axis_format` | _string_ | The **Y Axis Format** widget |
| `y_axis_zero` | _N/A_ | _Deprecated?_ |
| Field | Type | Notes |
| ---------------- | -------- | ---------------------------- |
| `y_axis_2_label` | _N/A_ | _Deprecated?_ |
| `y_axis_format` | _string_ | The **Y Axis Format** widget |
| `y_axis_zero` | _N/A_ | _Deprecated?_ |

Note the `y_axis_format` is defined under various section for some charts.

### Other

| Field | Type | Notes |
| -------------- | -------- | ------------ |
| `color_scheme` | _string_ | |
| Field | Type | Notes |
| -------------- | -------- | ----- |
| `color_scheme` | _string_ | |

### Unclassified

| Field | Type | Notes |
| ------------------------------- | ----- | ----- |
| `add_to_dash` | _N/A_ | |
| `code` | _N/A_ | |
| `collapsed_fieldsets` | _N/A_ | |
| `comparison type` | _N/A_ | |
| `country_fieldtype` | _N/A_ | |
| `default_filters` | _N/A_ | |
| `entity` | _N/A_ | |
| `expanded_slices` | _N/A_ | |
| `extra_filters` | _N/A_ | |
| `filter_immune_slice_fields` | _N/A_ | |
| `filter_immune_slices` | _N/A_ | |
| `flt_col_0` | _N/A_ | |
| `flt_col_1` | _N/A_ | |
| `flt_eq_0` | _N/A_ | |
| `flt_eq_1` | _N/A_ | |
| `flt_op_0` | _N/A_ | |
| `flt_op_1` | _N/A_ | |
| `goto_dash` | _N/A_ | |
| `import_time` | _N/A_ | |
| `label` | _N/A_ | |
| `linear_color_scheme` | _N/A_ | |
| `new_dashboard_name` | _N/A_ | |
| `new_slice_name` | _N/A_ | |
| `num_period_compare` | _N/A_ | |
| `period_ratio_type` | _N/A_ | |
| `perm` | _N/A_ | |
| `rdo_save` | _N/A_ | |
| `refresh_frequency` | _N/A_ | |
| `remote_id` | _N/A_ | |
| `resample_fillmethod` | _N/A_ | |
| `resample_how` | _N/A_ | |
| `rose_area_proportion` | _N/A_ | |
| `save_to_dashboard_id` | _N/A_ | |
| `schema` | _N/A_ | |
| `series` | _N/A_ | |
| `show_bubbles` | _N/A_ | |
| `slice_name` | _N/A_ | |
| `timed_refresh_immune_slices` | _N/A_ | |
| `userid` | _N/A_ | |
| Field | Type | Notes |
| ----------------------------- | ----- | ----- |
| `add_to_dash` | _N/A_ | |
| `code` | _N/A_ | |
| `collapsed_fieldsets` | _N/A_ | |
| `comparison type` | _N/A_ | |
| `country_fieldtype` | _N/A_ | |
| `default_filters` | _N/A_ | |
| `entity` | _N/A_ | |
| `expanded_slices` | _N/A_ | |
| `extra_filters` | _N/A_ | |
| `filter_immune_slice_fields` | _N/A_ | |
| `filter_immune_slices` | _N/A_ | |
| `flt_col_0` | _N/A_ | |
| `flt_col_1` | _N/A_ | |
| `flt_eq_0` | _N/A_ | |
| `flt_eq_1` | _N/A_ | |
| `flt_op_0` | _N/A_ | |
| `flt_op_1` | _N/A_ | |
| `goto_dash` | _N/A_ | |
| `import_time` | _N/A_ | |
| `label` | _N/A_ | |
| `linear_color_scheme` | _N/A_ | |
| `new_dashboard_name` | _N/A_ | |
| `new_slice_name` | _N/A_ | |
| `num_period_compare` | _N/A_ | |
| `period_ratio_type` | _N/A_ | |
| `perm` | _N/A_ | |
| `rdo_save` | _N/A_ | |
| `refresh_frequency` | _N/A_ | |
| `remote_id` | _N/A_ | |
| `resample_fillmethod` | _N/A_ | |
| `resample_how` | _N/A_ | |
| `rose_area_proportion` | _N/A_ | |
| `save_to_dashboard_id` | _N/A_ | |
| `schema` | _N/A_ | |
| `series` | _N/A_ | |
| `show_bubbles` | _N/A_ | |
| `slice_name` | _N/A_ | |
| `timed_refresh_immune_slices` | _N/A_ | |
| `userid` | _N/A_ | |
2 changes: 1 addition & 1 deletion superset-frontend/package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
"cover": "NODE_ENV=test jest --coverage",
"dev": "webpack --mode=development --colors --debug --watch",
"dev-server": "NODE_ENV=development BABEL_ENV=development node --max_old_space_size=4096 ./node_modules/webpack-dev-server/bin/webpack-dev-server.js --mode=development",
"prod": "node --max_old_space_size=4096 BABEL_ENV=production ./node_modules/webpack/bin/webpack.js --mode=production --colors",
"prod": "npm run build",
"build-dev": "cross-env NODE_OPTIONS=--max_old_space_size=8192 NODE_ENV=development webpack --mode=development --colors",
"build-instrumented": "cross-env NODE_ENV=development BABEL_ENV=instrumented webpack --mode=development --colors",
"build": "cross-env NODE_OPTIONS=--max_old_space_size=8192 NODE_ENV=production BABEL_ENV=production webpack --mode=production --colors",
Expand Down

0 comments on commit ff7b789

Please sign in to comment.