README.md

@cyclic.sh/s3fs

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.

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

  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. 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 Cyclic.sh may be found in "Data/Storage" tab in the user's Cyclic dashboard and will reset after 60 minutes.

  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. For example:

  const fs = require('@cyclic.sh/s3fs')(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('@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 (async/await)

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