1# write [![NPM version](https://img.shields.io/npm/v/write.svg?style=flat)](https://www.npmjs.com/package/write) [![NPM monthly downloads](https://img.shields.io/npm/dm/write.svg?style=flat)](https://npmjs.org/package/write) [![NPM total downloads](https://img.shields.io/npm/dt/write.svg?style=flat)](https://npmjs.org/package/write) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/write.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/write) 2 3> Write data to a file, replacing the file if it already exists and creating any intermediate directories if they don't already exist. Thin wrapper around node's native fs methods. 4 5## Install 6 7Install with [npm](https://www.npmjs.com/): 8 9```sh 10$ npm install --save write 11``` 12 13## Usage 14 15```js 16var writeFile = require('write'); 17``` 18 19## API 20 21### [writeFile](index.js#L40) 22 23Asynchronously writes data to a file, replacing the file if it already exists and creating any intermediate directories if they don't already exist. Data can be a string or a buffer. Returns a promise if a callback function is not passed. 24 25**Params** 26 27* `filepath` **{string|Buffer|integer}**: filepath or file descriptor. 28* `data` **{string|Buffer|Uint8Array}**: String to write to disk. 29* `options` **{object}**: Options to pass to [fs.writeFile](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback) and/or [mkdirp](https://github.com/substack/node-mkdirp) 30* `callback` **{Function}**: (optional) If no callback is provided, a promise is returned. 31 32**Example** 33 34```js 35var writeFile = require('write'); 36writeFile('foo.txt', 'This is content...', function(err) { 37 if (err) console.log(err); 38}); 39 40// promise 41writeFile('foo.txt', 'This is content...') 42 .then(function() { 43 // do stuff 44 }); 45``` 46 47### [.promise](index.js#L82) 48 49The promise version of [writeFile](#writefile). Returns a promise. 50 51**Params** 52 53* `filepath` **{string|Buffer|integer}**: filepath or file descriptor. 54* `val` **{string|Buffer|Uint8Array}**: String or buffer to write to disk. 55* `options` **{object}**: Options to pass to [fs.writeFile](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback) and/or [mkdirp](https://github.com/substack/node-mkdirp) 56* `returns` **{Promise}** 57 58**Example** 59 60```js 61var writeFile = require('write'); 62writeFile.promise('foo.txt', 'This is content...') 63 .then(function() { 64 // do stuff 65 }); 66``` 67 68### [.sync](index.js#L120) 69 70The synchronous version of [writeFile](#writefile). Returns undefined. 71 72**Params** 73 74* `filepath` **{string|Buffer|integer}**: filepath or file descriptor. 75* `data` **{string|Buffer|Uint8Array}**: String or buffer to write to disk. 76* `options` **{object}**: Options to pass to [fs.writeFileSync](https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options) and/or [mkdirp](https://github.com/substack/node-mkdirp) 77* `returns` **{undefined}** 78 79**Example** 80 81```js 82var writeFile = require('write'); 83writeFile.sync('foo.txt', 'This is content...'); 84``` 85 86### [.stream](index.js#L151) 87 88Uses `fs.createWriteStream` to write data to a file, replacing the file if it already exists and creating any intermediate directories if they don't already exist. Data can be a string or a buffer. Returns a new [WriteStream](https://nodejs.org/api/fs.html#fs_class_fs_writestream) object. 89 90**Params** 91 92* `filepath` **{string|Buffer|integer}**: filepath or file descriptor. 93* `options` **{object}**: Options to pass to [mkdirp](https://github.com/substack/node-mkdirp) and [fs.createWriteStream](https://nodejs.org/api/fs.html#fs_fs_createwritestream_path_options) 94* `returns` **{Stream}**: Returns a new [WriteStream](https://nodejs.org/api/fs.html#fs_class_fs_writestream) object. (See [Writable Stream](https://nodejs.org/api/stream.html#stream_class_stream_writable)). 95 96**Example** 97 98```js 99var fs = require('fs'); 100var writeFile = require('write'); 101fs.createReadStream('README.md') 102 .pipe(writeFile.stream('a/b/c/other-file.md')) 103 .on('close', function() { 104 // do stuff 105 }); 106``` 107 108## Release history 109 110### v1.0.2 - 2017-07-11 111 112* improved documentation 113 114### v1.0.0 - 2017-07-09 115 116**Added** 117 118* [promise support](#promise) 119 120**Changed** 121 122* The main export will now return a promise if no callback is passed 123 124## About 125 126### Related projects 127 128* [delete](https://www.npmjs.com/package/delete): Delete files and folders and any intermediate directories if they exist (sync and async). | [homepage](https://github.com/jonschlinkert/delete "Delete files and folders and any intermediate directories if they exist (sync and async).") 129* [read-data](https://www.npmjs.com/package/read-data): Read JSON or YAML files. | [homepage](https://github.com/jonschlinkert/read-data "Read JSON or YAML files.") 130* [read-yaml](https://www.npmjs.com/package/read-yaml): Very thin wrapper around js-yaml for directly reading in YAML files. | [homepage](https://github.com/jonschlinkert/read-yaml "Very thin wrapper around js-yaml for directly reading in YAML files.") 131* [write-data](https://www.npmjs.com/package/write-data): Write a YAML or JSON file to disk. Automatically detects the format to write based… [more](https://github.com/jonschlinkert/write-data) | [homepage](https://github.com/jonschlinkert/write-data "Write a YAML or JSON file to disk. Automatically detects the format to write based on extension. Or pass `ext` on the options.") 132* [write-json](https://www.npmjs.com/package/write-json): Write a JSON file to disk, also creates intermediate directories in the destination path if… [more](https://github.com/jonschlinkert/write-json) | [homepage](https://github.com/jonschlinkert/write-json "Write a JSON file to disk, also creates intermediate directories in the destination path if they don't already exist.") 133* [write-yaml](https://www.npmjs.com/package/write-yaml): Write YAML. Converts JSON to YAML writes it to the specified file. | [homepage](https://github.com/jonschlinkert/write-yaml "Write YAML. Converts JSON to YAML writes it to the specified file.") 134 135### Contributing 136 137Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new). 138 139### Contributors 140 141| **Commits** | **Contributor** | 142| --- | --- | 143| 33 | [jonschlinkert](https://github.com/jonschlinkert) | 144| 1 | [tunnckoCore](https://github.com/tunnckoCore) | 145 146### Building docs 147 148_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_ 149 150To generate the readme, run the following command: 151 152```sh 153$ npm install -g verbose/verb#dev verb-generate-readme && verb 154``` 155 156### Running tests 157 158Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command: 159 160```sh 161$ npm install && npm test 162``` 163 164### Author 165 166**Jon Schlinkert** 167 168* [github/jonschlinkert](https://github.com/jonschlinkert) 169* [twitter/jonschlinkert](https://twitter.com/jonschlinkert) 170 171### License 172 173Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert). 174Released under the [MIT License](LICENSE). 175 176*** 177 178_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on July 11, 2017._