turbo-gulp/targets/lib.d.ts

Gulp tasks to boost high-quality projects.

/// <reference types="gulp" />
/**
 * This module defines the _lib_ target type used to create libraries for other projects.
 *
 * In the following list of tasks, `{target}` represents the name of the target as defined by the `name` property
 * of the target options.
 * The _lib_ target provides the following tasks:
 *
 * ## {target}:build
 *
 * Performs a full build of the library to the build directory, used for development.
 * This copies the static assets and compiles the scripts.
 *
 * The following sub-tasks are available:
 * - `{target}:build:copy`: Only copy the static assets
 * - `{target}:build:script`: Only compile the scripts
 *
 * For distribution builds, use `{target:dist}`
 *
 * ## {target}:watch
 *
 * Watch the files and run incremental builds on change.
 * This useful during development to get build errors reported immediately or accelerate the code/test cycle.
 * You can combine it with _Nodemon_ to continuously restart your Node process when changing the source.
 *
 * ## {target}:dist
 *
 * Performs a full build of the library to the dist directory, used for distribution (ie. publication to _npm_).
 * This build creates a fully autonomous directory with its own `package.json`, source code, license file, etc.
 * This allows to use a different structure for distribution rather than structure of the repo, the main benefit is
 * to provide support for deep package imports (`import * as mod from "my-lib/deep/module"`) by placing the build
 * at the root of the package.
 * This build also allows you to remap the `package.json`, for example to set the version dynamically.
 *
 * The following sub-tasks are available:
 * - `{target}:dist:publish`: Publish the package to an _npm_ registry (it honors the `registry` option, to publish
 *   to private _npm_ registries such as _Verdaccio_). It uses the authentication token of the current user, this
 *   token is in `~/.npmrc`. For CI, you can use the following command to set the token the registry `npm.example.com`.
 *   (for the official registry, use `//registry.npmjs.org`):
 *   ```
 *   echo "//npm.example.com/:_authToken=\"${NPM_TOKEN}\"" > ~/.npmrc
 *   ```
 * - `{target}:dist:copy-src`: Only copy the source files to the build directory.
 * - `{target}:dist:package.json`: Copy (and eventually transform) the root `package.json` to the build directory.
 *
 * For development builds, use `{target:build}`.
 *
 * ## {target}:typedoc
 *
 * Generate _Typedoc_ documentation.
 *
 * ## {target}:typedoc:deploy
 *
 * Deploy the _Typedoc_ documentation using _git_. This can be used to easily deploy the documentation to the
 * `gh-pages` branch.
 *
 * ## {target}:clean
 *
 * Remove both the build and dist directories corresponding to this target.
 *
 * ## {target}:tsconfig.json
 *
 * Emit a `tsconfig.json` file corresponding to the configuration for this target. This allows to compile it using
 * the command line `tsc` program. This is also useful for IDE to auto-detect the configuration of the project.
 *
 * @module targets/lib
 */
/** (Placeholder comment, see christopherthielen/typedoc-plugin-external-module-name#6) */
import { Gulp, TaskFunction } from "gulp";
import { CopyOptions } from "../options/copy";
import { AbsPosixPath, RelPosixPath } from "../types";
import { PackageJson } from "../utils/project";
import { BaseTasks, TargetBase } from "./_base";
/**
 * Represents a Typescript library.
 * This is compatible with both browsers and Node.
 */
export interface LibTarget extends TargetBase {
    /**
     * Relative path for the main module (entry point of the lib) WITHOUT EXTENSION, relative to `project.srcDir`.
     * Default: `"index"`.
     */
    mainModule: RelPosixPath;
    /**
     * Path to the `typedoc` directory, relative to `project.rootDir`.
     * Use `null` to not generate a `typedoc` task.
     * Default: `join(project.rootDir, "typedoc")`.
     */
    typedoc?: TypedocOptions;
    /**
     * Options for distribution builds.
     * `false`: No distribution build
     * `true`: Distribution build with defaults
     * `DistOptions`: Provide custom options
     * Default: `false`, no distribution build.
     */
    dist?: true | false | DistOptions;
}
export interface DistOptions {
    /**
     * Directory used where the distribution builds will be written.
     * Default: `project.distDir`
     */
    readonly distDir?: RelPosixPath;
    /**
     * Copy the sources from `target.srcDir` to `target.dist.distDir`. Default: `true`.
     */
    readonly copySrc?: boolean;
    /**
     * Copy operations to perform when distributing the package.
     * The default copies the Markdown files at the project root (so you get `README.md`, `LICENSE.md`, ...).
     *
     * The base values are:
     * - `src`: `project.root`
     * - `dest`: `dist.distDir`
     */
    readonly copy?: CopyOptions[];
    readonly npmPublish?: NpmPublishOptions;
    /**
     * Optional function to apply when copying the `package.json` file to the dist directory.
     */
    packageJsonMap?(old: PackageJson): PackageJson;
}
export interface ResolvedDistOptions extends DistOptions {
    /**
     * Directory used for distribution builds.
     */
    readonly distDir: AbsPosixPath;
    /**
     * Copy the sources from `target.srcDir` to `target.dist.distDir`, and custom typings to `_custom-typings`.
     */
    readonly copySrc: boolean;
    /**
     * Optional function to apply when copying the `package.json` file to the dist directory.
     */
    packageJsonMap(old: PackageJson): PackageJson;
}
export interface TypedocOptions {
    /**
     * Path to the `typedoc` directory, relative to `project.rootDir`.
     * Use `null` to not generate a `typedoc` task.
     * Default: `join(project.rootDir, "typedoc")`.
     */
    readonly dir: RelPosixPath;
    readonly name: string;
    readonly deploy?: GitDeployOptions;
}
export interface ResolvedTypedocOptions extends TypedocOptions {
    readonly dir: AbsPosixPath;
}
export interface NpmPublishOptions {
    /**
     * Tag to use for this publication.
     *
     * Default: `"latest"`.
     */
    readonly tag?: string;
    /**
     * Path to the npm command-line program.
     *
     * Default: `"npm"` (assumes that `npm` is in the `$PATH`)
     */
    readonly command?: string;
}
export interface GitDeployOptions {
    readonly repository: string;
    readonly branch: string;
    readonly commitAuthor?: string;
}
export interface LibTasks extends BaseTasks {
    typedoc?: TaskFunction;
    typedocDeploy?: TaskFunction;
    dist?: TaskFunction;
    distCopy?: TaskFunction;
    distPublish?: TaskFunction;
    distPackageJson?: TaskFunction;
}
/**
 * Generates gulp tasks for the provided lib target.
 *
 * @param gulp Gulp instance used to generate tasks manipulating files.
 * @param targetOptions Target configuration.
 */
export declare function generateLibTasks(gulp: Gulp, targetOptions: LibTarget): LibTasks;
/**
 * Generates and registers gulp tasks for the provided lib target.
 *
 * @param gulp Gulp instance where the tasks will be registered.
 * @param targetOptions Target configuration.
 */
export declare function registerLibTasks(gulp: Gulp, targetOptions: LibTarget): LibTasks;