4 Temporary files, directories, and streams for Node.js.
6 Handles generating a unique file/directory name under the appropriate
7 system temporary directory, changing the file to an appropriate mode,
8 and supports automatic removal (if asked)
10 `temp` has a similar API to the `fs` module.
17 [![Build Status](https://travis-ci.org/bruce/node-temp.png)](https://travis-ci.org/bruce/node-temp)
19 Please let me know if you have problems running it on a later version of Node.js or
20 have platform-specific problems.
25 Install it using [npm](http://github.com/isaacs/npm):
29 Or get it directly from:
30 http://github.com/bruce/node-temp
35 You can create temporary files with `open` and `openSync`, temporary
36 directories with `mkdir` and `mkdirSync`, or you can get a unique name
37 in the system temporary directory with `path`.
39 Working copies of the following examples can be found under the
44 To create a temporary file use `open` or `openSync`, passing
45 them an optional prefix, suffix, or both (see below for details on
46 affixes). The object passed to the callback (or returned) has
50 { path: "/path/to/file",
51 , fd: theFileDescriptor
55 In this example we write to a temporary file and call out to `grep` and
56 `wc -l` to determine the number of time `foo` occurs in the text. The
57 temporary file is chmod'd `0600` and cleaned up automatically when the
58 process at exit (because `temp.track()` is called):
61 var temp = require('temp'),
63 util = require('util'),
64 exec = require('child_process').exec;
66 // Automatically track and cleanup files at exit
70 var myData = "foo\nbar\nfoo\nbaz";
72 // Process the data (note: error handling omitted)
73 temp.open('myprefix', function(err, info) {
75 fs.write(info.fd, myData);
76 fs.close(info.fd, function(err) {
77 exec("grep foo '" + info.path + "' | wc -l", function(err, stdout) {
78 util.puts(stdout.trim());
85 ### Want Cleanup? Make sure you ask for it.
87 As noted in the example above, if you want temp to track the files and
88 directories it creates and handle removing those files and directories
89 on exit, you must call `track()`. The `track()` function is chainable,
90 and it's recommended that you call it when requiring the module.
93 var temp = require("temp").track();
96 Why is this necessary? In pre-0.6 versions of temp, tracking was
97 automatic. While this works great for scripts and
98 [Grunt tasks](http://gruntjs.com/), it's not so great for long-running
99 server processes. Since that's arguably what Node.js is _for_, you
100 have to opt-in to tracking.
106 When tracking, you can run `cleanup()` and `cleanupSync()` anytime
107 (`cleanupSync()` will be run for you on process exit). An object will
108 be returned (or passed to the callback) with cleanup counts and
109 the file/directory tracking lists will be reset.
112 > temp.cleanupSync();
118 > temp.cleanup(function(err, stats) {
125 Note: If you're not tracking, an error ("not tracking") will be passed
128 ### Temporary Directories
130 To create a temporary directory, use `mkdir` or `mkdirSync`, passing
131 it an optional prefix, suffix, or both (see below for details on affixes).
133 In this example we create a temporary directory, write to a file
134 within it, call out to an external program to create a PDF, and read
135 the result. While the external process creates a lot of additional
136 files, the temporary directory is removed automatically at exit (because
137 `temp.track()` is called):
140 var temp = require('temp'),
142 util = require('util'),
143 path = require('path'),
144 exec = require('child_process').exec;
146 // Automatically track and cleanup files at exit
149 // For use with ConTeXt, http://wiki.contextgarden.net
150 var myData = "\\starttext\nHello World\n\\stoptext";
152 temp.mkdir('pdfcreator', function(err, dirPath) {
153 var inputPath = path.join(dirPath, 'input.tex')
154 fs.writeFile(inputPath, myData, function(err) {
156 process.chdir(dirPath);
157 exec("texexec '" + inputPath + "'", function(err) {
159 fs.readFile(path.join(dirPath, 'input.pdf'), function(err, data) {
168 ### Temporary Streams
170 To create a temporary WriteStream, use 'createWriteStream', which sits
171 on top of `fs.createWriteStream`. The return value is a
172 `fs.WriteStream` whose `path` is registered for removal when
173 `temp.cleanup` is called (because `temp.track()` is called).
176 var temp = require('temp');
178 // Automatically track and cleanup files at exit
181 var stream = temp.createWriteStream();
182 stream.write("Some data");
183 // Maybe do some other things
189 You can provide custom prefixes and suffixes when creating temporary
190 files and directories. If you provide a string, it is used as the prefix
191 for the temporary name. If you provide an object with `prefix`,
192 `suffix` and `dir` keys, they are used for the temporary name.
194 Here are some examples:
196 * `"aprefix"`: A simple prefix, prepended to the filename; this is
198 * `{prefix: "aprefix"}`: A simple prefix, prepended to the filename
199 * `{suffix: ".asuffix"}`: A suffix, appended to the filename
200 (especially useful when the file needs to be named with specific
201 extension for use with an external program).
202 * `{prefix: "myprefix", suffix: "mysuffix"}`: Customize both affixes
203 * `{dir: path.join(os.tmpDir(), "myapp")}`: default prefix and suffix
204 within a new temporary directory.
205 * `null`: Use the defaults for files and directories (prefixes `"f-"`
206 and `"d-"`, respectively, no suffixes).
208 In this simple example we read a `pdf`, write it to a temporary file with
209 a `.pdf` extension, and close it.
212 var fs = require('fs'),
213 temp = require('temp');
215 fs.readFile('/path/to/source.pdf', function(err, data) {
216 temp.open({suffix: '.pdf'}, function(err, info) {
218 fs.write(info.fd, contents);
219 fs.close(info.fd, function(err) {
221 // Do something with the file
227 ### Just a path, please
229 If you just want a unique name in your temporary directory, use
233 var fs = require('fs');
234 var tempName = temp.path({suffix: '.pdf'});
235 // Do something with tempName
238 Note: The file isn't created for you, and the mode is not changed -- and it
239 will not be removed automatically at exit. If you use `path`, it's
245 If you want to use the module with [Grunt](http://gruntjs.com/), make sure you
246 use `async()` in your Gruntfile:
249 module.exports = function (grunt) {
250 var temp = require("temp");
251 temp.track(); // Cleanup files, please
252 grunt.registerTask("temptest", "Testing temp", function() {
254 var done = this.async(); // Don't forget this!
256 grunt.log.writeln("About to write a file...");
257 temp.open('tempfile', function(err, info) {
258 // File writing shenanigans here
259 grunt.log.writeln("Wrote a file!")
261 done(); // REALLY don't forget this!
268 For more information, see the [Grunt FAQ](http://gruntjs.com/frequently-asked-questions#why-doesn-t-my-asynchronous-task-complete).
280 You can find the repository at:
281 http://github.com/bruce/node-temp
283 Issues/Feature Requests can be submitted at:
284 http://github.com/bruce/node-temp/issues
286 I'd really like to hear your feedback, and I'd love to receive your
292 Copyright (c) 2010-2014 Bruce Williams. This software is licensed
293 under the MIT License, see LICENSE for details.