Skip to content


Repository files navigation

Drop in replacement for the Node.js fs library backed by AWS S3. Use the same methods as fs and enjoy the convenience of S3 buckets without the hassle of AWS.

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 (for async/await functions):

    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. A warning will show in the terminal.

  • Environment Variables - The internal S3 client will use AWS credentials if they are set in the local environment. Variables provided by may be found in "Data/Storage" tab in the user's Cyclic dashboard and will reset after 60 minutes.

  • Client Credentials - The library also accepts standard S3 client parameters at initialization. For example:

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

Using Methods

The supported methods have the same API as Node.js fs and can be written as follows:

  • 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 (async/await)
      const fs = require('')(S3_BUCKET_NAME)
      async function run(){
        const json = JSON.parse(await fs.readFile('test/_read.json'))