Skip to content

Commit c15d3a9

Browse files
WookieFPVWookieFPV
committed
chore: improve README.md
1 parent 477b33c commit c15d3a9

File tree

1 file changed

+65
-96
lines changed

1 file changed

+65
-96
lines changed

‎README.md‎

Lines changed: 65 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,117 +1,86 @@
11
# build-cache-s3 [![npm][npm-image]][npm-url] ![npm][npm-dl-stats]
22

3-
🚀 Drastically speed up your `npx expo run:[android|ios]` builds!
3+
Speed up your `npx expo run:[android|ios]` builds by caching native builds in S3-compatible storage. If a matching cache is found, it downloads and launches the build, skipping native compilation.
44

5-
This Expo plugin adds intelligent caching for your builds using S3-compatible storage. If a matching cached build is found, it downloads and launches the build, allowing you to bypass the often time-consuming native compilation step entirely.
6-
7-
> **Warning**: This plugin requires Expo SDK 53 or higher to function correctly.
5+
> **Requires Expo SDK 53+**
86
97
## ✨ Features
108

11-
* **⚡️ Blazing Fast Builds**: Skip native compilation on repeat builds, leading to significantly faster iteration and development cycles.
12-
* **☁️ S3-Compatible Storage**: Works seamlessly with AWS S3, Cloudflare R2, DigitalOcean Spaces, MinIO, LocalStack, and more.
13-
* **Flexible Configuration**: Configure via `app.json`/`app.config.js`, a dedicated JSON file, or ENV variables.
14-
* **Environment-Aware Caching**: Control cache behavior (`read`, `read-write`, `no-cache`) for local development and CI/CD environments.
15-
16-
## 🚀 Getting Started
17-
18-
1. **Install the plugin**:
19-
20-
```bash
21-
npm install --save-dev build-cache-s3
22-
# or
23-
yarn add --dev build-cache-s3
24-
```
25-
26-
2. **Add it to your `app.json` or `app.config.js`**:
27-
28-
Integrate the plugin into your Expo configuration under the `experiments.buildCacheProvider` key.
29-
30-
```json
31-
{
32-
"expo": {
33-
"experiments": {
34-
"buildCacheProvider": {
35-
"plugin": "build-cache-s3",
36-
"options": {
37-
"bucket": "your-s3-bucket-name",
38-
"region": "your-aws-region",
9+
- **⚡️ Fast Builds**: Skip native compilation on repeat builds.
10+
- **☁️ S3-Compatible**: Works with AWS S3, Cloudflare R2, DigitalOcean Spaces, MinIO, LocalStack, and more.
11+
- **Flexible Config**: Configure via `app.json`, `app.config.js`, `build-cache-s3.json`, or ENV variables.
12+
- **Environment-Aware**: Control cache behavior for local and CI/CD environments.
13+
14+
## Getting Started
15+
16+
1. **Install**:
17+
```bash
18+
npm install --save-dev build-cache-s3
19+
# or
20+
yarn add --dev build-cache-s3
21+
```
22+
2. **Configure**:
23+
Add to your Expo config under `experiments.buildCacheProvider`:
24+
```json
25+
{
26+
"expo": {
27+
"experiments": {
28+
"buildCacheProvider": {
29+
"plugin": "build-cache-s3",
30+
"options": {
31+
"bucket": "your-s3-bucket-name",
32+
"region": "your-aws-region",
3933
"endpoint": "https://s3.your-aws-region.amazonaws.com",
40-
"accessKeyId": "preferably use environment variables",
41-
"secretAccessKey": "preferably use environment variables"
42-
}
43-
}
44-
}
45-
}
46-
}
47-
```
48-
49-
> **Security Note**: For production environments and CI/CD pipelines, it's **highly recommended** to use environment variables for sensitive credentials like `accessKeyId` and `secretAccessKey` instead of hardcoding them in your configuration files (`AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`) .
34+
"accessKeyId": "hardcoded or preferably use environment variables instead",
35+
"secretAccessKey": "hardcoded or preferably use environment variables instead"
36+
}
37+
}
38+
}
39+
}
40+
}
41+
```
42+
> **Tip**: Use environment variables for credentials (`accessKeyId`, `secretAccessKey`).
5043
5144
## 🛠️ Configuration
5245

53-
The plugin offers various configuration options to fine-tune its behavior for different environments and storage providers.
54-
55-
| Property | Description | Default | Required | Environment Variable |
56-
|:------------------|:----------------------------------------------------------------------------------------------------------------------|:---------------|:---------|:-------------------------------|
57-
| `bucket` | The name of the S3 bucket dedicated to caching builds. | N/a | Yes | `BUILD_CACHE_S3_BUCKET` |
58-
| `region` | The AWS region where your S3 bucket resides. | N/a | Yes | `BUILD_CACHE_S3_REGION` |
59-
| `endpoint` | The custom endpoint URL for your S3-compatible storage provider (e.g., Cloudflare R2, MinIO). | AWS S3 default | No | `BUILD_CACHE_S3_ENDPOINT` |
60-
| `accessKeyId` | Your AWS access key ID. Reads `BUILD_CACHE_S3_ACCESS_KEY_ID` environment variable (recommended) | N/a | No | `BUILD_CACHE_S3_ACCESS_KEY_ID` |
61-
| `secretAccessKey` | Your AWS secret access key. Reads `BUILD_CACHE_S3_SECRET_ACCESS_KEY` environment variable (recommended) | N/a | No | `BUILD_CACHE_S3_SECRET_ACCESS_KEY` |
62-
| `forcePathStyle` | Set to `true` to use path-style URLs for S3 objects. Some S3-compatible providers don't support virtual-hosted style. | `false` | No | `BUILD_CACHE_S3_FORCE_PATH_STYLE` |
63-
| `localMode` | Determines cache behavior during local development: `read`, `read-write`, or `no-cache`. | `'read-write'` | No | `BUILD_CACHE_S3_LOCAL_MODE` |
64-
| `ciMode` | Determines cache behavior during CI/CD runs: `read`, `read-write`, or `no-cache`. | `'read-write'` | No | `BUILD_CACHE_S3_CI_MODE` |
65-
| `localCacheDir` | Directory for local cache storage. | OS default | No | `BUILD_CACHE_S3_CACHE_DIR` |
66-
| `localCacheGcTimeDays` | Number of days before local cache files are deleted. | `30` | No | `BUILD_CACHE_S3_CACHE_GC_DAYS` |
67-
| `debug` | Enable debug logging. | `false` | No | `BUILD_CACHE_S3_DEBUG` |
46+
| Property | Description | Required | Env Variable |
47+
|:-----------------------|:---------------------------------------------------|:---------|:-----------------------------------|
48+
| `bucket` | S3 bucket for caching builds | Yes | `BUILD_CACHE_S3_BUCKET` |
49+
| `region` | AWS region | Yes | `BUILD_CACHE_S3_REGION` |
50+
| `endpoint` | Custom S3 endpoint (for non-AWS providers) | No | `BUILD_CACHE_S3_ENDPOINT` |
51+
| `accessKeyId` | AWS access key ID | No | `BUILD_CACHE_S3_ACCESS_KEY_ID` |
52+
| `secretAccessKey` | AWS secret access key | No | `BUILD_CACHE_S3_SECRET_ACCESS_KEY` |
53+
| `forcePathStyle` | Use path-style URLs (for some S3 providers) | No | `BUILD_CACHE_S3_FORCE_PATH_STYLE` |
54+
| `localMode` | Local cache mode: `read`, `read-write`, `no-cache` | No | `BUILD_CACHE_S3_LOCAL_MODE` |
55+
| `ciMode` | CI cache mode: `read`, `read-write`, `no-cache` | No | `BUILD_CACHE_S3_CI_MODE` |
56+
| `localCacheDir` | Local cache directory | No | `BUILD_CACHE_S3_CACHE_DIR` |
57+
| `localCacheGcTimeDays` | Days before local cache files are deleted | No | `BUILD_CACHE_S3_CACHE_GC_DAYS` |
58+
| `debug` | Enable debug logging | No | `BUILD_CACHE_S3_DEBUG` |
6859

6960
### Configuration Methods
70-
71-
You have several flexible options for configuring `build-cache-s3`:
72-
73-
1. **In `app.json` or `app.config.js`**:
74-
See the [Getting Started](#🚀-getting-started) section for an example.
75-
76-
2. **In a dedicated config file (`build-cache-s3.json`)**:
77-
Create a `build-cache-s3.json` file in your project's root or your home directory. This is useful for sharing configuration across multiple projects or keeping sensitive details out of version control.
78-
79-
```json
80-
// build-cache-s3.json
81-
{
82-
"bucket": "your-s3-bucket-name",
83-
"region": "your-aws-region",
84-
"endpoint": "https://s3.your-aws-region.amazonaws.com",
85-
"accessKeyId": "your-access-key-id",
86-
"secretAccessKey": "your-secret-access-key"
87-
}
88-
```
89-
90-
## ☁️ S3 Bucket Setup & Recommendations
91-
92-
To leverage this plugin, you'll need an S3-compatible bucket. It's highly recommended to create a dedicated bucket solely for this purpose to maintain organization, simplify management, and apply specific lifecycle policies.
93-
94-
### Important Recommendations:
95-
96-
* **Dedicated Bucket**: Use a bucket specifically for build caching. Do not mix it with other application data.
97-
* **Lifecycle Policy**: Implement a **lifecycle policy** on your bucket to automatically delete old cached builds (e.g., after 7-30 days) to control storage use and costs.
98-
99-
### Supported S3-Compatible Storage Providers
100-
101-
This plugin is designed to work with any S3-compatible object storage. Just ensure you set the `endpoint` option correctly for your provider.
102-
103-
Some popular options include:
104-
61+
- **Expo config**: See above.
62+
- **Environment variables**: Set the required variables in your shell or CI/CD environment.
63+
- **Config file**: Create `build-cache-s3.json` in your project or home directory.
64+
```json
65+
{
66+
"bucket": "your-s3-bucket-name",
67+
"region": "your-aws-region"
68+
}
69+
```
70+
71+
## S3 Bucket Setup
72+
- Use a dedicated bucket for build caching.
73+
- Set a lifecycle policy to auto-delete old builds (e.g., after 7-30 days).
74+
75+
### Supported Providers
10576
* [**AWS S3**](https://aws.amazon.com/s3/)
10677
* [**Cloudflare R2**](https://www.cloudflare.com/developer-platform/r2/) (simple setup with 15GB free tier)
10778
* [**MinIO**](https://min.io/product/s3-compatibility)
10879
* [**LocalStack**](https://www.localstack.cloud/)
10980
* [**DigitalOcean Spaces**](https://www.digitalocean.com/products/spaces)
11081

111-
> If you only need local caching without S3, consider using the [**expo-build-disk-cache**](https://github.com/WookieFPV/expo-build-disk-cache) plugin.\
112-
> If you want remote caching without needing a s3 bucket, consider using the [**eas-build-cache-provider**](https://docs.expo.dev/guides/cache-builds-remotely/) plugin.
113-
114-
82+
> For local-only caching, see [expo-build-disk-cache](https://github.com/WookieFPV/expo-build-disk-cache).\
83+
> For remote caching without managing your own S3 storage, see [eas-build-cache-provider](https://docs.expo.dev/guides/cache-builds-remotely/).
11584
11685
## ❤️ Acknowledgments
11786

0 commit comments

Comments
 (0)