@cyclic.sh/s3fs
v1.2.9
Published
Drop in replacement for Node.js fs library backed by AWS S3 with local filesystem fallback.
Downloads
1,709
Readme
@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:
orconst fs = require('@cyclic.sh/s3fs')
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. 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')) }