# Write File
> Write data to a file.
## Usage
```javascript
var writeFile = require( '@stdlib/fs/write-file' );
```
#### writeFile( file, data\[, options], clbk )
Asynchronously write `data` to a `file`.
```javascript
var join = require( 'path' ).join;
var fpath = join( __dirname, 'examples', 'fixtures', 'file.txt' );
writeFile( fpath, 'beep boop\n', onWrite );
function onWrite( error ) {
if ( error ) {
throw error;
}
}
```
The `data` argument may be either a `string` or a [`Buffer`][@stdlib/buffer/ctor].
```javascript
var join = require( 'path' ).join;
var string2buffer = require( '@stdlib/buffer/from-string' );
var fpath = join( __dirname, 'examples', 'fixtures', 'file.txt' );
writeFile( fpath, string2buffer( 'beep boop\n' ), onWrite );
function onWrite( error ) {
if ( error ) {
throw error;
}
}
```
The function accepts the same `options` and has the same defaults as [`fs.writeFile()`][node-fs].
#### writeFile.sync( file, data\[, options] )
Synchronously writes `data` to a `file`.
```javascript
var join = require( 'path' ).join;
var fpath = join( __dirname, 'examples', 'fixtures', 'file.txt' );
var err = writeFile.sync( fpath, 'beep boop\n' );
if ( err instanceof Error ) {
throw err;
}
```
The function accepts the same `options` and has the same defaults as [`fs.writeFileSync()`][node-fs].
## Notes
- The difference between this `writeFile.sync` and [`fs.writeFileSync()`][node-fs] is that [`fs.writeFileSync()`][node-fs] will throw if an `error` is encountered (e.g., if given a non-existent directory path) and this API will return an `error`. Hence, the following anti-pattern
```javascript
var fs = require( 'fs' );
// Check for directory path existence to prevent an error being thrown...
if ( fs.existsSync( '/path/to' ) ) {
fs.writeFileSync( '/path/to/file.txt', 'beep boop\n' );
}
```
can be replaced by an approach which addresses existence via `error` handling.
```javascript
var writeFile = require( '@stdlib/fs/write-file' );
// Explicitly handle the error...
var err = writeFile.sync( '/path/to/file.txt', 'beep boop\n' );
if ( err instanceof Error ) {
// You choose what to do...
throw err;
}
```
## Examples
```javascript
var join = require( 'path' ).join;
var writeFile = require( '@stdlib/fs/write-file' );
var fpath = join( __dirname, 'examples', 'fixtures', 'file.txt' );
// Synchronously write data to a file:
var err = writeFile.sync( fpath, 'beep boop\n', 'utf8' );
// returns null
console.log( err instanceof Error );
// => false
// Asynchronously write data to a file:
writeFile( fpath, 'beep boop\n', onWrite );
function onWrite( error ) {
if ( error ) {
console.error( 'Error: %s', error.message );
}
console.log( 'Success!' );
}
```
* * *
## CLI
### Usage
```text
Usage: write-file [options]
Options:
-h, --help Print this message.
-V, --version Print the package version.
--enc, --encoding encoding Encoding. Default: 'utf8'.
--flag flag Flag. Default: 'r'.
--mode mode Mode. Default: 0o666.
```
### Notes
- Relative output file paths are resolved relative to the current working directory.
- Errors are written to `stderr`.
- File contents should be provided over `stdin` as part of a [standard stream][standard-stream] pipeline.
### Examples
```bash
$ printf 'beep boop\n' | write-file ./examples/fixtures/file.txt
```
[node-fs]: https://nodejs.org/api/fs.html
[@stdlib/buffer/ctor]: https://www.npmjs.com/package/@stdlib/buffer-ctor
[standard-stream]: http://en.wikipedia.org/wiki/Pipeline_%28Unix%29