@cyclic.sh/s3fs

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

Supported methods

@cyclic.sh/s3fs 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

Installation

npm install @cyclic.sh/s3fs

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

• Callbacks and Sync methods:

  const fs = require('@cyclic.sh/s3fs')(S3_BUCKET_NAME)

• Promises

  const fs = require('@cyclic.sh/s3fs/promises')(S3_BUCKET_NAME)

• On cyclic.sh

  • Alternatively, when using with cyclic.sh 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('@cyclic.sh/s3fs') 

    or

    const fs = require('@cyclic.sh/s3fs/promises') 

Authentication

Authenticating the client:

• cyclic.sh –
  • When deploying on cyclic.sh, 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

  AWS_REGION
  AWS_ACCESS_KEY_ID
  AWS_SECRET_KEY
  AWS_SECRET_ACCESS_KEY
  

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

  const fs = require('@cyclic.sh/s3fs')(S3_BUCKET_NAME, {
          region: ...
          credentials: {...}
      })

Using Methods

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

• Sync

    const fs = require('@cyclic.sh/s3fs')(S3_BUCKET_NAME)
    const json = JSON.parse(fs.readFileSync('test/_read.json'))

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

    const fs = require('@cyclic.sh/s3fs/promises')(S3_BUCKET_NAME)
    async function run(){
      const json = JSON.parse(await fs.readFile('test/_read.json'))
    }