Repository files navigation

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

@cyclic.sh/s3fs supports the followingfs methods operating on AWS S3:

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

npm install @cyclic.sh/s3fs

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

• Callbacks and Sync methods:

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

• Promises (for async/await functions):

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

• On Cyclic.sh

  • Alternatively, when using withcyclic.sh or if the environment variableCYCLIC_BUCKET_NAME is set to an S3 bucket name, initialization can happen without specifying a bucket:

    constfs=require('@cyclic.sh/s3fs')

    or

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

Authenticating the client:

• cyclic.sh -

  • When deploying oncyclic.sh, credentials are already available in the environment.
  • The bucket name is also available under theCYCLIC_BUCKET_NAME variable.
  • Read more:Cyclic Environment Variables

• Local Mode - When no credentials are available, the client will fall back to usingfs 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_REGIONAWS_ACCESS_KEY_IDAWS_SECRET_KEYAWS_SECRET_ACCESS_KEY

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

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

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

• Sync

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

• Callbacks

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

• Promises (async/await)

  constfs=require('@cyclic.sh/s3fs/promises')(S3_BUCKET_NAME)asyncfunctionrun(){constjson=JSON.parse(awaitfs.readFile('test/_read.json'))}