Skip to main content
Ant provides a filesystem module that works like Node.js’s fs/promises API. You can import it using the ant:fs specifier or the Node-compatible node:fs and fs specifiers — all three point to the same implementation. Functions return promises by default, so you can use await directly without touching a callback-style API.

​
Importing the module

All imports resolve to the same module. Use ant:fs in new code to make the runtime dependency explicit.

​
Reading files

​
As a Buffer

readFile without an encoding option returns a Buffer — a Node-compatible subclass of Uint8Array. 
import { readFile } from 'ant:fs';
import { join } from 'ant:path';

const file = await readFile(join(import.meta.dirname, 'meow.txt'));
return new Response(file || 'none');

​
As a string

Pass 'utf8' as the second argument to get a decoded string instead. 
import { readFile } from 'ant:fs';

const content = await readFile('./config.json', 'utf8');
const config = JSON.parse(content);
Use import.meta.dirname (the ESM equivalent of __dirname) to build paths relative to the current module rather than the process working directory.

​
Writing files

​
Write a new file

import { writeFile } from 'ant:fs';

await writeFile('./output.txt', 'Hello from Ant!');

// Write binary data
const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
await writeFile('./hello.bin', data);

​
Append to a file

import { appendFile } from 'ant:fs';

await appendFile('./log.txt', `[${new Date().toISOString()}] server started\n`);
writeFile overwrites the target file if it already exists. Use appendFile when you want to add to an existing file.

​
Checking if a file exists

import { existsSync } from 'ant:fs';

if (existsSync('./config.json')) {
  const content = await readFile('./config.json', 'utf8');
  const config = JSON.parse(content);
}
existsSync is synchronous. Use it for quick existence checks before performing async operations.

​
File metadata

import { stat } from 'ant:fs';

const info = await stat('./data.json');
console.log(info.size);    // file size in bytes
console.log(info.mtime);   // Date of last modification
console.log(info.isFile()); // true
console.log(info.isDirectory()); // false

​
Directory operations

​
Create a directory

import { mkdir } from 'ant:fs';

await mkdir('./cache/responses', { recursive: true });
Pass { recursive: true } to create any missing parent directories — equivalent to mkdir -p.

​
List directory contents

import { readdir } from 'ant:fs';

const entries = await readdir('./src');
console.log(entries); // ['index.ts', 'utils.ts', 'types/']

​
Deleting and renaming

​
Delete a file

import { unlink } from 'ant:fs';

await unlink('./temp.txt');

​
Rename or move a file

import { rename } from 'ant:fs';

await rename('./old-name.txt', './new-name.txt');
// Also works across directories:
await rename('./tmp/draft.txt', './published/article.txt');

​
API reference

​
readFile(path, encoding?)
function
Reads a file. Returns Promise<Buffer> without an encoding, or Promise<string> when encoding is 'utf8'.
​
writeFile(path, data)
function
Writes data to path, overwriting any existing file. Returns Promise<void>.
​
appendFile(path, data)
function
Appends data to path, creating the file if it does not exist. Returns Promise<void>.
​
stat(path)
function
Returns Promise<Stats> with file metadata including size, mtime, isFile(), and isDirectory().
​
mkdir(path, options?)
function
Creates a directory. Pass { recursive: true } to create missing parents. Returns Promise<void>.
​
readdir(path)
function
Lists files and directories in path. Returns Promise<string[]>.
​
unlink(path)
function
Deletes a file. Returns Promise<void>.
​
rename(from, to)
function
Renames or moves a file. Returns Promise<void>.
​
existsSync(path)
function
Returns true if the path exists. Synchronous — no promise needed.

​
The ant:path module

Use ant:path to build file paths safely across platforms. Import it alongside ant:fs. 
import { readFile } from 'ant:fs';
import { join, dirname, basename, extname, resolve } from 'ant:path';

const dir = import.meta.dirname;
const file = join(dir, 'assets', 'logo.png');

console.log(basename(file));        // "logo.png"
console.log(extname(file));         // ".png"
console.log(dirname(file));         // "/path/to/assets"
console.log(resolve('..', 'data')); // absolute path
​
join(...parts)
function
Joins path segments using the OS separator and normalizes the result.
​
resolve(...parts)
function
Resolves a sequence of paths into an absolute path.
​
dirname(path)
function
Returns the directory portion of a path.
​
basename(path)
function
Returns the last component of a path (the filename).
​
extname(path)
function
Returns the file extension, including the dot (e.g. ".ts").