@gravity-ui/app-builder

@gravity-ui/app-builder ·

Develop and build your client-server projects, powered by typescript and webpack.

Install

npm install --save-dev @gravity-ui/app-builder

Usage

@gravity-ui/app-builder provides CLI (npx app-builder). You can view available commands with the --help flag.

Develop your project

npx app-builder dev # to view supported options add the --help flag.

Build your project

npx app-builder build # to view supported options add the --help flag.

Configuration

You can use any of these files:

• app-builder.config.ts
• app-builder.config.js
• app-builder.config.json
• app-builder property in your package.json

You can also specify a custom filename using the --config flag

TypeScript/JavaScript

import {defineConfig} from '@gravity-ui/app-builder';

export default defineConfig({
  client: {
    // client settings
  },
  server: {
    // server settings
  },
});

Conditional config

If the config needs to be conditionally determined, it can export a function instead:

import {defineConfig} from '@gravity-ui/app-builder';

export default defineConfig(async function (
  /** @type dev | build */
  command,
  /**
   * values specified with --env flag
   *
   * @type {[k in string]: string}
   *
   * @example
   *   With follow command:
   *       app-build dev --env=path.to.member1=value1 --env=path.to.member2=value2
   *   you get:
   *       env = {path: {to: {member1: 'value1', member2: 'value2'}}}
   */
  env,
) {
  return {
    verbose: command === 'dev',
    client: {
      // client settings
    },
    server: {
      // server settings
    },
  };
});

export default config;

package.json

{
  "app-builder": {
    "client": {
      // client settings
    },
    "server": {
      // server settings
    }
  },
  "scripts": {
    "dev": "app-builder dev",
    "build": "app-builder build"
  }
}

Common

• target (client | server) — select compilation unit.
• verbose (boolean) - turn on verbose output.

Server

app-builder compiles server with typescript. Default folder for server code is src/server. There is must be file tsconfig.json

{
  "compilerOptions": {
    "outDir": "../../dist/server"
  }
}

and index.ts - server entrypoint.

outDir - must be configured to place compiled files to {rootDir}/dist/server. The server is started with the command node {rootDir}/dist/server/index.js.

Options

All server settings are used only in dev mode:

• port (number | true) — specify port that server listens. The port will be used to pass through requests from the client to the server. If set to true, the port will be selected automatically. The server is started with the command APP_PORT=${port} node dist/server/index.js --port ${port}.
• watch (string[]) — by default app-builder monitors only src/server directory. If you need to watch other directories, specify them here.
• watchThrottle (number) — use to add an extra throttle, or delay restarting.
• inspect/inspectBrk (number | true) — listen for a debugging client on specified port. If specified true, try to listen on 9229.

Client

app-builder bundles client with webpack. Client code must be in src/ui folder. src/ui/entries - each file in this folder is used as entrypoint. dist/public/build is output directory for bundles.

Options

All paths must be specified relative rootDir of the project.

• modules (string[]) — Tell webpack what directories should be searched when resolving modules. modules automatically populates with baseUrl from src/ui/tsconfig.json.
• alias (Record<string, string>) — Create aliases to import or require certain modules more easily, more

With this {rootDir}/src/ui/tsconfig.json:

{
  "compilerOptions": {
    "baseDir": ".",
    "paths": {
      "~units": ["units/*"]
    }
  }
}

modules will contain ["{rootDir}/src"] and aliases - {"~units": ["{rootDir}/src/units"]};

• includes (string[]) — additional compilation paths. Example: includes: ['node_modules/my-lib', 'src/shared']
• images (string[]) — Additional paths for images. Example: images: ['node_modules/my-lib/img']
• icons (string[]) — Additional paths for svg icons. By default, all svgs with paths including icons/ will be processed. Example: icons: [node_modules/@fortawesome/fontawesome-pro/svgs]
• publicPathPrefix (string) — publicPath prefix, will be added to /build/
• symlinks (boolean) — Follow symbolic links while looking for a file. more
• externals — specify dependencies that shouldn't be resolved by webpack, but should become dependencies of the resulting bundle. more
• node — include polyfills or mocks for various node stuff. more
• fallback — Redirect module requests when normal resolving fails. more
• polyfill — allow enable Node.js process object polyfill.
• hiddenSourceMap (boolean=true) - if false - source maps will be generated for prod builds
• disableSourceMapGeneration (boolean) — disable sourcemap generation;
• definitions — add additional options to DefinePlugin. more
• newJsxTransform (boolean=true) — use new JSX Transform.
• svgr (SvgrConfig) — svgr plugin options. more
• entryFilter (string[]) — filter used entrypoints.
• excludeFromClean (string[]) — do not clean provided paths before build.
• disableForkTsChecker (boolean) - do not use ForkTsChecker.

Dev build

• devServer (Object) — webpack dev server options.
  • ipc (string) — the Unix socket to listen to. If ipc and port are not defined, then the socket {rootDir}/dist/run/client.sock is used.
  • port (number | true) — specify a port number to listen for requests on. If true, the free port will be selected automatically.
  • webSocketPath (string) — tells clients connected to devServer to use the provided path to connect. Default is ${publicPathPrefix}/build/sockjs-node.
  • type ('https') — allow to serve over HTTPS.
  • options (import('https').ServerOptions) — allow to provide your own certificate.
• watchOptions — a set of options used to customize watch mode, more
• disableReactRefresh (boolean) — disable react-refresh in dev mode.
• detectCircularDependencies (true | CircularDependenciesOptions) - detect modules with circular dependencies, more

Production build

• analyzeBundle (true | statoscope) — tools to analyze bundle.
  • true — enable webpack-bundle-analyzer plugin. Report generated to dist/public/build/stats.html
  • statoscope — enable statoscope plugin. Reports generated to dist/public/build/stats.json and dist/public/build/report.json
• reactProfiling (boolean) — use react profiler API in production, this option also disable minimization. The API is required by React developers tools for profile.
• cdn (CdnUploadConfig | CdnUploadConfig[]) - upload bundled client files to CDN.
  • bucket (string) — bucket name
  • prefix (string) — path to files inside the bucket
  • region (string) — AWS region or any string
  • endpoint (string) - cdn host to upload files
  • compress (boolean) - upload also gzip and brotli compressed versions of files
  • additionalPattern (string[]) — patterns for uploading additional files. By default, only files generated by webpack are loaded.

Optimization

• vendors (string[]) — additional libraries for vendor chunk
• momentTz — settings for moment-timezone (by default data is truncated);
• contextReplacement (object)
  • highlight.js (string[]) — list of language names to include, e.g. ['javascript', 'python', 'bash'];
  • locale: (string[]=['ru']) — list of moment.js or day.js locales to include, e.g. ['de', 'es']. Locale En is always present.
• safari10 (boolean) — Enables safari10 terser's option. Terser options

Monaco editor support

• monaco (object) — use monaco-editor-webpack-plugin

  • fileName (string) — custom filename template for worker scripts
  • languages (string[]) - include only a subset of the languages supported.
  • features (string[]) - include only a subset of the editor features.
  • customLanguages (IFeatureDefinition[]) - include custom languages (outside of the ones shipped with the monaco-editor).

Changelog

0.3.0 (2023-05-08)

⚠ BREAKING CHANGES

• LibraryConfig: move newJsxTransform option under lib property

Features

• config: add defineConfig helper (31daecc)
• server: use APP_PORT env variable to pass port to server (6b14651)
• storybook: use configureServiceWebpackConfig for libraries too (4204cf9)

Bug Fixes

• client: use newJsxTransform in svgr options (cd01f55)
• LibraryConfig: move newJsxTransform option under lib property (847a38c)

docs

• add documentation for services (d78b63b)