Nine Pounds of Mayonnaise

    ct-mapapps-gulp-js

    0.7.4 • Public • Published

    ct-mapapps-gulp-js

    A support lib for gulp based mapapps projects.

    Features:

    • .js transpile
    • .ts transpile (experimental)
    • .vue transpile (including experimental support for lang="ts")
    • .less compile
    • static error checking of js and vue files (linting)
    • theme dependency support
    • vuetify theme support
    • css compression
    • js compression
    • API Documentation (jsdoc to Markdown and typedoc)
    • Since version 0.1.x babel 7.x is used for JavaScript > transpilation!
    • Since version 0.2.x gulp 4.x is used.

    Installation

    npm install ct-mapapps-gulp-js --save-dev

    For Test execution puppeteer in version ^13.0.0 is required to be a dependency in your project. For vue compilation vue-template-compiler in a version matching your vue version is required to be a dependency in your project.

    Usage

    Scenario map.apps remote project with js transpilation only

    Create a gulpfile.js:

    const gulp = require("gulp");
    const mapapps = require("ct-mapapps-gulp-js");
    
    mapapps.registerTasks({});
    
    gulp.task("default", gulp.series("copy-resources", "js-lint", "js-transpile"));

    Scenario map.apps remote project with themes and js transpilation

    Create a gulpfile.js:

    const gulp = require("gulp");
    const run_sequence = require("run-sequence");
    const mapapps = require("ct-mapapps-gulp-js");
    
    mapapps.registerTasks({
        // a custom theme
        themes: ["sample_theme"],
        // custom theme is based on theme-everlasting
        hasBaseThemes: true
    });
    
    gulp.task("default", gulp.series("copy-resources", "themes-copy", gulp.parallel("js-transpile", "themes-compile")));

    Using the experimental typescript support

    Typescript support is enabled for every .ts source file in the project. All Typescript files are transpiled using babel. No typechecks are performed by the transpilation or watch tasks.

    In order to get IDE, linting and typechecking to work, create a tsconfig.json file in your project's root directory:

    npm install --save-dev typescript
    npx tsc --init --declaration --target esnext --outdir lib --module amd

    You may also want to configure the included/excluded source files in your tsconfig.json, for example:

    {
        "compilerOptions": {
            // ...
        },
        "include": ["./src/main/js/**/*"],
        "exclude": ["./node_modules/**/*"]
    }

    In your package.json, add two scripts for typechecking:

    "scripts": {
        "type-check": "tsc --noEmit",
        "type-check:watch": "npm run type-check -- --watch",
    }

    Use npm run type-check (run once) or npm run type-check:watch (run in the background) to check for type errors. The "--noEmit" flag in the script definition is important: transpilation is done via gulp/babel.

    Using typescript in .vue files

    Use lang="ts" in your script section:

    <template>
        <span>Hello World</span>
    </template>
    <script lang="ts">
    // Typescript!
    export default /* ... */;
    </script>

    To make imports of vue files work from typescript files, create a file in your source folder called vue-shims.d.ts:

    declare module "*.vue" {
        import Vue from "vue";
        export default Vue;
    }

    You must also make the vue typings available to the typescript compiler. TODO: We might distribute d.ts files for vue with mapapps in the future.

    The following should work after the steps above:

    import MyComponent from "./MyComponent.vue";

    Creating type definitions

    The create-types task will auto-create typescript definition files (d.ts) from existing code. Types are generated from typescript files (ts), but can be created from plain javascript files (js) as well. To generate types from javascript files, set the property allowJs to true in the tsconfig.json. The typescript compiler will try to make best guesses based on existing code and JSDocs. To specify the output directory for the generated types, the property typingsDestLocation is used. To be able to publish the created types, a package.json file for the resulting npm package has to be present at typingsTemplateLocation. If the version in the package.json ends with -SNAPSHOT then it will automatically replaced by a -next.<timestamp> postfix to prepare publishing to npm.

    This feature is experimental.

    gulp create-types

    Provided Tasks

    clean

    Deletes options.destLocation

    watch

    Watches for file changes and processes them

    copy-resources

    Copies all files in options.srcLocation to options.destLocation excluding options.copyIgnore

    js-lint

    Checks all .js files for typical erorrs. The goal is using es-lint.

    The linting needs to be activated on watch, use options.lintOnWatch flag to enable it.

    See options.lintIgnore and options.lintOptions for the default settings.

    js-transpile

    Transpiles all .js, .ts, and .vue files in options.srcLocation to options.destLocation. If options.compress is enabled then the files are compressed, too. TypeScript transpilation is experimental.

    themes-copy

    Copies themes to options.destLocation with theme dependencies. If options.hasBaseThemes is true, then theme options.baseCommonThemeName is copied to options.themesDestLocation. If options.themeChangeTargets is configured, then defined themes are copied into the target themes. If options.hasVuetify is true, then vuetify resources are copied to all themes listed in options.themeChangeTargets under key vuetify. If options.hasVuetify is true, then a vuetify-mapping.json is expected in the target themes. Which is used to rewrite the vuetify stylus configuration.

    themes-compile

    Compile *.less and *.styl files of the themes options.themes.

    themes-compress

    Compress all <theme>/styles/styles.css files.

    This task is not supported in watch mode.

    css-compress

    Compress additional css files listed in options.compressCssFiles array. The listed files need to be relative to options.destLocation. The files will be modified in place. This task is not supported in watch mode.

    create-api-docs

    Creates API.md files in bundles marked with a .apidoc file. The option createAPIDoc must be enabled.

    The .apidoc file can be empty or contain JSON contents. This sample shows the default values:

    {
        "include": ["**/*.js"],
        "exclude": ["**/tests/**/*"]
    }
    

    create-types

    Creates type definition files. This feature is experimental.

    run-browser-tests

    Starts a headless browser and loads test html pages which support test execution detection, e.g. the runner.html files of the intern.js test runner provided by map.apps.

    For Test execution puppeteer in version ^3.0.0 is required to be a dependency in your project.

    You can preconfigure the urls to the test files by defining the option runBrowserTests. Or parametrize the task via command line:

    gulp run-browser-tests --tests http://localhost:${jetty.server.port}/js/tests/test-base/runTests.html

    Since 0.4.3 follwoing syntax is supported as workarround for frontend-maven-plugin issue:

    gulp run-browser-tests "--tests=http://a... http://b..."

    rollup-build

    Experimental rollup build process, replacing the js-transpile task. The rollup-build task will search the entire "srcLocation" directory for bundles (detected by looking for manifest.json or package.json). Every bundle may have an build.config.js configuration file, which will be loaded when the task runs.

    Example content of build.config.js:

    module.exports = {
        // Required, the chosen build type. Currently, only "bundle" is supported.
        type: "bundle",
    
        // List of public entry point modules. Only these files will be importable by other bundles, all other
        // private module files within the current bundle will be bundled together and will *not* be exported.
        //
        // `entryPoints` can be a string (single entry point), an array of strings, or an object.
        // The object syntax allows the user to name the entry points differently than the input files:
        //
        //  Example:
        //      entryPoints: { "custom-name": "input-file.js" }
        //
        // Note that, by default, file extensions are stripped from entry points when using the string or array syntax. For example, the compilation of `bar.ts` below will result in a `bar.js` module, not in `bar.ts.js`.
        // Extensions will not be stripped when using the object syntax.
        entryPoints: ["foo.js", "bar.ts"]
    
        // Optional, defaults to true. When this is true, all files within the "nls" folder will automatically
        // be treated as entry points and will therefore be usable with the usual dojo nls system.
        i18n: true,
    
        // Optional, defaults to true. All files within the "tests" folder will automatically be treated as
        // entry points.
        tests: true,
    
        // Optional, defaults to an empty array. Allows bundling of external modules from the `node_modules` folder.
        //
        //  Example:
        //      // in your build.config.js
        //      npmDependencies: ["external-lib", "another-lib/nested/module"]
        //
        //      // in a source file:
        //      import something from "external-lib"
        //      import somethingElse from "another-lib/nested/module";
        //
        // Note that the precise import path must be used; glob patterns are possible.
        // The entire source code of the referenced node module and all its transitive dependencies will be included in the built bundle, so use this option with care.
        npmDependencies: [],
    
        // Optional expert configuration (know what you are doing!).
        // Allows configuring the supported browser versions on a per-bundle basis.
        // Currently only supported if babel is used to transpile source code.
        // Entries here will override the defaults from the global configuration.
        //targets: {
        //    firefox: 78,
        //    edge: 90,
        //    chrome: 90,
        //    safari: 13
        //}
    
    };

    The build.config.js may either export an object as displayed above or a Promise to such an object. Note that ES6 module syntax is not currently supported within this file.

    Special import syntax

    rollup-build supports special import identifiers to access files or virtual modules that are not JavaScript modules. This can be used, for example, to embed the content of text files into the compiled JavaScript output:

    import content from "text!./some-text-file.txt";
    console.log(content); // Prints the text stored in the text file

    Reference:

    • import foo from "text!./some-file";

      Makes the file's content available as a string. The file should contain UTF-8 encoded text. The content will be included in the bundled output as JavaScript constant, so the input file does not need to be present in the compiled bundle.

    • import { configProperty } from "build-config!;

      Imports the static configuration value configProperty into the current file. The value must be registered with the rollupConfig option (see below). Only plain old JavaScript data is supported (without cycles).

      Alternative syntax:

      • import configProperty from "build-config!configProperty";
      • import * as allConfigProperties from "build-config!";
    • import { sourceId } from "source-info!"

      Will provide the source file id of the importing module, without its file extension. This value is not affected by bundling etc and will always reflect the state in the source directory.

      Example:

      my-bundle/my-directory/my-file.ts:

      import { sourceId } from "source-info!";
      console.debug(sourceId); // prints my-bundle/my-directory/my-file

    Default options

    {
                // open for extensions
                plugins: defaultPlugins.slice(0),
    
                // enable debug output
                debug: false,
    
                // enable check for existing files during copy of resources
                incremental: true,
    
                // enable uglify during js-transpile task
                compress: false,
    
                // ignore files during js-compress task
                compressIgnore: [],
    
                // source directory
                srcLocation: "./src/main/js",
    
                // build output directory
                destLocation: "./target/webapp/js",
    
                // typings output directory
                typingsDestLocation: "./target/typings",
    
                // directory for package.json of typings project
                typingsTemplateLocation: "./src/main/resources/typings",
    
                // enables creation of API.md files in folders marked with .apidoc
                createAPIDoc: false,
    
                // list of urls to trigger js test execution
                runBrowserTests: [],
    
                // enable babel transpile for all .js and .vue files
                // if disabled a .babelrc with empty object '{}' as body must be created to
                // ensure that a bundle is transpiled.
                forceTranspile: true,
    
                // Defines how sourcemaps are created: "inline" | "file" | "none";
                sourceMaps: "inline",
    
                // path patterns which should be ignored by js-transpile goal
                transpileIgnore: [],
    
                // enables watch support of transpile task
                // use it to disable watching of js-transpile, e.g. if pure rollup build is used
                transpileEnableWatch: true,
    
                // enable babel-runtime transformation(requires babel-runtime as available package
                transpileUseBabelRuntime: false,
    
                // enables the useBuiltIns flag during transformation
                transpileUseBuiltIns: false,
    
                // babel transpile targets: https://babeljs.io/docs/en/babel-preset-env#browserslist-integration
                // eslint-disable-next-line max-len
                // https://dev.azure.com/conterra/TeamProdEng/_wiki/wikis/Team-ct-Technologies-Product-Engineering.wiki/281/JavaScript-Compilation-Settings
                transpileTargets: {
                    firefox: 78,
                    edge: 90,
                    chrome: 90,
                    safari: 13
                },
    
                // babel transpile settings
                transpileOptions: function (): TranspileOptions {
                    const presets = [
                        [
                            "@babel/env",
                            {
                                targets: this.transpileTargets,
                                debug: this.debug,
                                modules: "amd",
                                useBuiltIns: this.transpileUseBuiltIns
                            }
                        ],
                        ["@babel/typescript"]
                    ];
    
                    const plugins = [
                        [injectModulePlugin],
                        [importMetaAmd],
                        ["@babel/plugin-syntax-dynamic-import"],
                        ["@babel/plugin-syntax-import-meta"],
                        ["@babel/proposal-class-properties"],
                        ["@babel/proposal-object-rest-spread"],
                        ["@babel/plugin-proposal-private-methods"],
                        ["@babel/plugin-proposal-private-property-in-object"],
                        ["@babel/plugin-proposal-numeric-separator"],
                        ["@babel/plugin-transform-modules-amd", { strictMode: false }]
    
                    ];
                    const useBabelRuntime = this.transpileUseBabelRuntime;
                    if (useBabelRuntime) {
                        const runtimeOptions =
                            typeof useBabelRuntime === "object"
                                ? useBabelRuntime
                                : { helpers: true, polyfill: true, regenerator: true, moduleName: "babel-runtime" };
                        plugins.push(["@babel/transform-runtime", runtimeOptions]);
                    }
                    return {
                        presets: presets,
                        plugins: plugins,
                        assumptions: {
                            privateFieldsAsProperties: true
                        }
                    };
                },
    
                // which files should be ignored in tasks 'copy-resources'
                copyIgnore: "**/*.{vue,ts,js}",
    
                // which files should be ignored during linting by default
                lintIgnore: " ",
    
                // enables/disables linting on watch
                lintOnWatch: false,
    
                // if enabled first error will stop build process
                lintFailFast: false,
    
                // the default js lint options directly passed to gulp-eslint
                lintOptions: {
                    envs: ["browser"],
                    parserOptions: {
                        "ecmaVersion": 2018,
                        "sourceType": "module"
                    },
                    baseConfig: {
                        extends: [
                            "eslint:recommended",
                            "plugin:vue/recommended"
                        ]
                    },
                    rules: {},
                    globals: ["module"]
                },
    
                // source directory of theme bundles
                themesSrcLocation: "./src/main/js/bundles",
    
                // build output directory for theme bundles
                themesDestLocation: "./target/webapp/js/bundles",
    
                // enables 'styles/**' copy from source to destination during 'theme-copy' task
                // this is not required if copy-resources task is used
                copyThemeSources: false,
    
                // names of custom theme bundles
                themes: [],
    
                // lookup from theme bundle names to target themes
                // e.g.:
                //            themeChangeTargets: {
                //                "theme-everlasting": [
                //                    "theme-summer",
                //                    "theme-spring",
                //                    "theme-winter",
                //                    {
                //                        name: "theme-liveconfiguration",
                //                        filter: [
                //                            "**/bundles/DataForm.less",
                //                            "**/bundles/ToolButton.less",
                //                            "**/bundles/Toolset.less",
                //                            "**/dijit/**",
                //                            "**/dojox/**",
                //                            "**/images/**",
                //                            "**/ui/**"
                //                        ]
                //                    }],
                //                    // special key 'vuetify' to define copy targets for vuetify stylus sources
                //                    "vuetify": ["theme-everlasting", "theme-summer", "theme-spring", "theme-winter"]
                //            }
                themeChangeTargets: {},
    
                // define that own themes are based on map.apps base themes
                // this will trigger a copy of "theme-common" to target theme folder
                // and the copy of "theme-everlasting" sources to the custom themes.
                hasBaseThemes: false,
    
                // define the name of the base theme, e.g. theme-everlasting
                baseThemeName: "theme-everlasting",
    
                // define the name of the common theme, e.g. theme-common
                baseCommonThemeName: "theme-common",
    
                // define the base themes source location
                baseThemesLocation: "./target/unpacked/layout",
    
                // defines that themes are dependent from vuetify
                hasVuetify: false,
    
                // Tests will not be included in the build if this is set to false.
                // This is useful for release builds, when an optimized version of the bundle is desired.
                rollupBuildTests: true,
    
                // Static values that can be imported via `import { foo } from "build-config!"`;
                // Values must be plain JavaScript values (not including functions) without cycles.
                // Values used this way will be embedded into the built JavaScript.
                // "build-config!" imports will not be present in the compiled output.
                rollupConfig: {}
    }

    Developer Hints

    Compile TypeScript -> JavaScript:

    npm run build

    Compiled javascript files are written into the dist folder.

    Use npm run watch instead for continuous compilation in watch mode.

    Run tests locally (requires built output):

    npm run test

    Debug tests locally:

    npm run test-debug

    Releasing:

    The publish command will automatically build the source code, so one can simply write:

    npm publish

    Keywords

    Install

    npm i ct-mapapps-gulp-js

    DownloadsWeekly Downloads

    186

    Version

    0.7.4

    License

    Apache-2.0

    Unpacked Size

    323 kB

    Total Files

    92

    Last publish

    Collaborators

    • a.frank
    • jessebluemr
    • schneiderlars
    • julkuh
    • m-scherpi
    • mbeckem_conterra
    • conterrade