@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')
- Alternatively, when using with cyclic.sh or if the environment variable
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')) }