Nemo's Parental Misguidance

    turbo-gulp
    TypeScript icon, indicating that this package has built-in type declarations

    0.22.1 • Public • Published

    Turbo Gulp

    Gulp tasks to boost high-quality projects.

    npm GitHub repository Build status Codecov

    This package was known as demurgos-web-build-tools before v0.15.2 (2017-11-09).

    This project started out because I wanted to avoid repeating complex configurations in every one of my projects. I solved it by centralizing most of logic for the tasks I need in this package. To further reduce the overhead of the configuration, the defaults use a sensible directory structure for Node projects.

    The main features are:

    • Support for multiple targets in a single project (for example lib and example)
    • Typescript builds, with support for custom typings, watch mode and custom compiler options
    • Tslint verification with type information
    • Mocha unit tests
    • Code coverage with c8
    • Typedoc generation
    • Assets management: copy resources

    Installation

    Install the library as a dev-dependency:

    npm install -D turbo-gulp

    Builds of the master branch are also regularly released using the next tag:

    npm install -D turbo-gulp@next

    Quick start

    TODO: Add better guide to configure repo and Travis CI, code coverage and codecov integrations. For the moment, take a look at this reference project: Incident.

    Then use it in your Gulp file, here is an example:

    // Import the build tools and the gulp instance for this project
    import * as buildTools from "turbo-gulp";
    import * as gulp from "gulp";
     
    // Project config shared by all the targets
    const project: buildTools.Project = {
      root: __dirname,
      packageJson: "package.json",
      buildDir: "build",
      distDir: "dist",
      srcDir: "src",
    };
     
    // Configuration for a "library" target
    const lib: buildTools.LibTarget = {
      // Project-wide config
      project,
      // Name (used as a prefix for the tasks)
      name: "lib",
      // Override srcDir
      srcDir: "src/lib",
      scripts: ["**/*.ts"],
      mainModule: "index",
      tscOptions: {
        skipLibCheck: true,
      },
      typedoc: {
        dir: "typedoc",
        name: "Example lib",
      },
      copy: [
        {
          name: "json",
          files: ["**/*.json"],
        },
      ],
      clean: {
        dirs: ["build/lib", "dist/lib"],
      },
    };
     
    // Generate and register project-wide tasks
    buildTools.projectTasks.registerAll(gulp, project);
    // Generate and register the tasks for the lib target
    buildTools.registerLibTasks(gulp, lib);

    You can then start using the tasks, for example gulp lib:build. Use gulp --tasks to list all the tasks. Check the documentation for the list of available tasks and configuration.

    Recommended project layout

    Here

    .
    ├── build/          # Development builds
    ├── dist/           # Distributed files (this goes to npm)
    ├── docs/           # Custom documentation for the library
    ├── src/            # Scripts, assets and tests
    | ├── lib/          # Library source code
    | └── test/         # Tests source code
    ├── CHANGELOG.md    # Description of the changes for each version
    ├── CONTRIBUTING.md # How to build and work on the project
    ├── LICENSE.md      # License file
    ├── NOTICE.md       # Notice for third-party tools (required by some licenses)
    ├── README.md       # Projects presentation
    ├── package.json    # Project's metadata
    ├── tsconfig.ts     # Default TS config file, used for the gulp file and to help the IDE
    └── gulpfile.ts     # Definition of Gulp tasks

    Usage

    The build tools use the following hierarchy:

    • Project: It represents a unit of code to implement a library or application, it usually corresponds to a git repo or a single gulp file. A project is a set of targets (see below). The project configuration is shared by all the targets, it defines the general structure of your project: what is the root directory, the build directory, the base Typescript options, etc.
    • Target: A target represents a unit of output. You can have some shared source code and use it to build multiple targets: for example, a library importable by other projects, a runnable demo, a test build using Mocha, a bundled version for the browser, etc. The target options are specific to each type of output and allow you to configure how each task is applied.
    • Task: A task represents an operation provided by a target: build, run, test, etc. This is what you actually use when calling Gulp. The task names have the form targetName:taskName. For example to generate the documentation of the library target lib using Typedoc, you can use gulp lib:typedoc. There are main tasks to do high-level actions, and other tasks for fine-grained that are mostly available to integrate with other tools.

    License

    MIT License

    Keywords

    none

    Install

    npm i turbo-gulp

    DownloadsWeekly Downloads

    101

    Version

    0.22.1

    License

    MIT

    Unpacked Size

    1.04 MB

    Total Files

    169

    Last publish

    Collaborators

    • demurgos