Menu Close


Drop in replacement for the Node.js fs library backed by AWS S3.

Discord CI semantic-release: angular

npm (scoped) node-current (scoped) code size

Supported methods supports the following fs methods operating on AWS S3:

  • writeFile / writeFileSync
  • readFile / readFileSync
  • exists / existsSync
  • rm / rmSync
  • stat / statSync
  • unlink / unlinkSync
  • readdir / readdirSync
  • mkdir / mkdirSync
  • rmdir / rmdirSync

Example Usage


npm install

Require in the same format as Node.js fs, specifying an S3 Bucket:

  • Callbacks and Sync methods:

    const fs = require('')(S3_BUCKET_NAME)
  • Promises

    const fs = require('')(S3_BUCKET_NAME)
  • On

    • Alternatively, when using with or if the environment variable CYCLIC_BUCKET_NAME is set to an S3 bucket name, initialization can happen without specifying a bucket:
      const fs = require('') 


      const fs = require('') 


Authenticating the client:

    • When deploying on, credentials are already available in the environment
    • The bucket name is also available under the CYCLIC_BUCKET_NAME variable
    • read more: Cyclic Environment Variables
  • Local Mode – When no credentials are available – the client will fall back to using fs and the local filesystem with a warning.
  • Environment Variables – the internal S3 client will use AWS credentials if set in the environment

  • Client Credentials – the library also accepts standard S3 client parameters at initialization:

    const fs = require('')(S3_BUCKET_NAME, {
            region: ...
            credentials: {...}

Using Methods

The supported methods have the same API as Node.js fs:

  • Sync

      const fs = require('')(S3_BUCKET_NAME)
      const json = JSON.parse(fs.readFileSync('test/_read.json'))
  • Callbacks
    const fs = require('')(S3_BUCKET_NAME) fs.readFile('test/_read.json', (error,data)=>{ const json = JSON.parse(data) })
  • Promises

      const fs = require('')(S3_BUCKET_NAME)
      async function run(){
        const json = JSON.parse(await fs.readFile('test/_read.json'))
View Source Code
Posted in Development