# gulp-transform > A Gulp plugin for applying custom transformations to the contents of files Latest version **3.0.5** (published 2017-07-29) · MIT license · 0 weekly downloads ## Install ```sh npm install gulp-transform pnpm add gulp-transform yarn add gulp-transform bun add gulp-transform ``` ## Health **Score 25/100 (F)** — status: abandoned. Positive: has types; no vulnerabilities; high quality score. Warnings: low downloads; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 3.0.5 | | Published | 2017-07-29 | | First published | 2016-01-10 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Node | >=4 | | Dependencies | 4 | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 9 | | Author | Akim McMath | | Maintainers | akim-mcmath | | Keywords | gulpplugin, gulp, transform, replace, map, typescript | ## Links - npm: https://www.npmjs.com/package/gulp-transform - Repository: https://github.com/mcmath/gulp-transform - Homepage: https://github.com/mcmath/gulp-transform#readme - Issues: https://github.com/mcmath/gulp-transform/issues - npm.io page: https://npm.io/package/gulp-transform ## Dependencies (4) - [tslib](https://npm.io/package/tslib.md) ^1.7.1 - [gulp-util](https://npm.io/package/gulp-util.md) ^3.0.8 - [@types/node](https://npm.io/package/@types/node.md) * - [@types/gulp-util](https://npm.io/package/@types/gulp-util.md) * ## Alternatives - [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads - [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads - [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads - [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads - [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads ## Recent versions - 3.0.5 (latest) — 2017-07-29 - 3.0.4 — 2017-07-29 - 3.0.3 — 2017-07-29 - 3.0.2 — 2017-07-29 - 3.0.1 — 2017-07-29 - 3.0.0 — 2017-07-29 - 2.0.0 — 2017-05-11 - 1.1.0 — 2016-10-19 - 1.0.8 — 2016-06-29 - 1.0.7 — 2016-06-10 - 1.0.6 — 2016-02-11 - 1.0.5 — 2016-02-10 - 1.0.4 — 2016-02-05 - 1.0.3 — 2016-01-23 - 1.0.2 — 2016-01-16 - … 1 more at https://npm.io/package/gulp-transform/versions ## README # gulp-transform [![version][versionBadge]][npm] [![build][buildBadge]][build] [![coverage][coverageBadge]][coverage] [![dependencies][dependenciesBadge]][dependencies] A [Gulp][gulp] plugin for applying custom transformations to the contents of files. ## Install Install via [npm][npm]: ```sh npm install --save-dev gulp gulp-transform ``` ## Usage ### Synchronous usage This example adds a timestamp to the beginning of each source file. The comment format is inferred from the file extension. Files with unrecognized extensions are not modified. #### gulpfile.js ```js const gulp = require('gulp'); const transform = require('gulp-transform'); const path = require('path'); const TIMESTAMP = Date(); gulp.task('timestamp', () => { return gulp.src('src/**/*') .pipe(transform('utf8', timestamp)) .pipe(gulp.dest('out')); }); function timestamp(content, file) { switch (path.extname(file.path)) { case '.js': case '.ts': return `// ${TIMESTAMP}\n\n${content}`; case '.coffee': return `# ${TIMESTAMP}\n\n${content}`; default: return content; } } ``` #### src/hello.js ```js console.log('Hello, world.'); ``` #### out/hello.js ```js // Thu Jul 27 2017 15:56:14 GMT-0700 (PDT) console.log('Hello, world.'); ``` ### Asynchronous usage This example uses [xml2js][xml2js] to convert XML to JSON. The callback returns a [Promise][promise] since the operation is asynchronous. #### gulpfile.js ```js const gulp = require('gulp'); const transform = require('gulp-transform'); const rename = require('gulp-rename'); const xml2js = require('xml2js'); gulp.task('xml-to-json', () => { return gulp.src('src/**/*.xml') .pipe(transform('utf8', xmlToJson)) .pipe(rename({ extname: '.json' })) .pipe(gulp.dest('out')); }); function xmlToJson(content) { return new Promise((resolve, reject) => { xml2js.parseString(content, (error, data) => { if (error) { reject(error); } else { resolve(JSON.stringify(data, null, 2)); } }); }); } ``` #### src/cities.xml ```xml Amsterdam Rotterdam The Hague ``` #### out/cities.json ```json { "cities": { "city": [ "Amsterdam", "Rotterdam", "The Hague" ] } } ``` ## API ### transform([options], callback) Creates a stream that transforms the contents of [File][vinylFile] objects. Files in both streaming and buffer mode are accepted. To transform contents as a string, a [character encoding][encoding] must be specified; otherwise, contents will be passed to the callback as a [Buffer][nodeBuffer]. The contents of each File are replaced with the return value of the callback. Or, to perform an asynchronous transformation, a [Promise][promise] may be returned.
Parameter Type Description
[options]

object

string

null

An optional options object or a value indicating an encoding. If passed as an object, the following properties are are accepted as options:

  • encoding - string | null - An encoding supported by Node.js or null to indicate no encoding. Defaults to null.
  • thisArg - any - The value of this within callback. Defaults to undefined.

If passed as a string or null, it is interpreted as the encoding option.

If no encoding is given, callback is called with a Buffer object containing the contents of the file. Otherwise, it is called with a string created with buffer.toString(encoding).

callback function

A function that transforms the contents of each file. It is invoked with two arguments:

  • contents - Buffer | string - The contents of the file. If no encoding is given, contents will be a Buffer; otherwise, it will be a string.
  • file - File - The File object whose contents are being transformed. Use this to access metadata about the file, e.g., its filename.

The contents of the file are replaced with the return value of the callback. For asynchronous transformations, a Promise may be returned. The return or completion value must have the same type as contents.

The value of this within the callback may be set with the thisArg option; otherwise, this will be undefined.

## TypeScript [TypeScript][typescript] declarations are included in the package. ```sh npm i -D typescript ts-node gulp @types/gulp gulp-transform ``` #### gulpfile.ts ```ts import gulp = require("gulp"); import transform = require("gulp-transform"); gulp.task("build", () => { gulp.src("src/**/*") .pipe(transform("utf8", () => { /* transform contents */ })) .pipe(gulp.dest("out")); }); ``` ## License Copyright © 2016–2017 Akim McMath. Licensed under the [MIT License][license]. [gulp]: http://gulpjs.com/ [npm]: https://npmjs.org/package/gulp-transform [versionBadge]: https://img.shields.io/npm/v/gulp-transform.svg?style=flat-square [license]: LICENSE [buildBadge]: https://img.shields.io/travis/mcmath/gulp-transform/master.svg?style=flat-square [build]: https://travis-ci.org/mcmath/gulp-transform [coverageBadge]: https://img.shields.io/coveralls/mcmath/gulp-transform/master.svg?style=flat-square&service=github [coverage]: https://coveralls.io/github/mcmath/gulp-transform?branch=master [dependenciesBadge]: https://img.shields.io/gemnasium/mcmath/gulp-transform.svg?style=flat-square [dependencies]: https://gemnasium.com/mcmath/gulp-transform [xml2js]: https://github.com/Leonidas-from-XIV/node-xml2js [vinylFile]: https://github.com/gulpjs/vinyl#instance-methods [encoding]: https://nodejs.org/dist/latest/docs/api/buffer.html#buffer_buffers_and_character_encodings [nodeBuffer]: https://nodejs.org/dist/latest-v8.x/docs/api/buffer.html [promise]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise [typescript]: https://www.typescriptlang.org/ --- _Source: https://npm.io/package/gulp-transform · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._