pt
/
superset
mirror of https://github.com/apache/superset.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: reword and cleanup docs for local dev server (#11869)

This commit is contained in:
Jesse Yang 2021-01-10 23:36:01 -08:00 committed by GitHub
parent 23263da9f3
commit ff7b789931
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 115 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

225
CONTRIBUTING.md
View File

@ -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)
@ -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)
@ -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 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.
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.
#### nvm and node
#### Prerequisite
##### 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:
@ -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
#### Install dependencies
#### Installing 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
@ -436,40 +439,40 @@ cd superset-frontend
npm ci
```
#### Building
#### Build assets
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.
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
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)
@ -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",
}
```
@ -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
@ -831,7 +834,6 @@ 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
@ -839,15 +841,16 @@ 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.
@ -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
@ -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
@ -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
superset-frontend/package.json
View File

@ -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",