Nook

A pantry compatible perishable data storage service hosted with Cloudflare Workers.

This project aims to provide a drop-in replacement for Pantry, with the same API and data format. If you prefer to own your data and have more control over it, Nook is the perfect solution for you.

Great for small sized projects when you need a simple key-value store without the hassle of setting up a database or rely on third-party services.

• 📦 Pantry Compatible - Nook is a drop-in replacement for Pantry, with the same API and data format.
• 🔒 Secure - Data encrypted at rest with Cloudflare Workers KV
• 🚀 Fast - Hosted on Cloudflare Workers, Nook is fast and reliable
• 💰 Free - Can be hosted under the Workers free plan of a Cloudflare account

Usage

Pre-requisites

• A Cloudflare account

Setting up Nook

1. Clone or fork this repository
2. npm install
3. npm run init and follow the prompts to create your pantry (data store)
4. From the init command output
   1. Note down the generated Pantry ID
   2. Copy the kv_namespaces config to the wrangler.toml file
5. Run npm run cf-typegen to generate the types for the Cloudflare Workers KV bindings
6. npm run publish to deploy Nook to Cloudflare Workers

Manual Initialisation

If you prefer to manually set up Nook, you can follow these steps:

1. Create a new namespace in Cloudflare Workers KV and note down the namespace ID.
2. Generate your own Pantry ID. This can be any string you like, but if your worker is public, it is recommended to use a random string to prevent others from accessing your data.
3. Add the following to your wrangler.toml file:

   [[kv_namespaces]]
   binding = "<your pantry id>"
   id = "<your KV namespace id>"

4. Run npm run cf-typegen to generate the types for the Cloudflare Workers KV bindings.

Using Nook

Once you have deployed Nook, you can use it as a drop-in replacement for Pantry.

If you are using a Pantry client, you can simply replace the Pantry domain or base url with your Cloudflare Workers domain.

# Create a Basket
curl -X POST https://your-nook-url.cloudflare.workers.dev/apiv1/pantry/your-pantry-id/basket/yourBasket \
  -H "Content-Type: application/json" \
  -d '{"city": "New York"}'

# Get Basket
curl https://your-nook-url.cloudflare.workers.dev/apiv1/pantry/your-pantry-id/basket/yourBasket

# Update Basket
curl -X PUT https://your-nook-url.cloudflare.workers.dev/apiv1/pantry/your-pantry-id/basket/yourBasket \
  -H "Content-Type: application/json" \
  -d '{"state": "NY"}'

# And so on... see Pantry API documentation for more routes

Data Persistence

Nook currently emulates the ephemeral nature of Pantry. Data is stored in Cloudflare Workers KV with a time-to-live (TTL) of 30 days. This means that data will be automatically deleted after 30 days of inactivity.

If you need data to persist indefinitely, you can modify the BASKET_TTL_SECONDS value in the wrangler.toml file to a higher or lower value. Setting it to 0 will make data persist indefinitely.

[vars]
BASKET_TTL_SECONDS = 0 # Set to 0 for indefinite persistence

References

• Pantry
• Pantry API Documentation
• Cloudflare Workers - Nook is deployed to Cloudflare Workers
• Cloudflare Workers KV - Nook uses Workers KV to store data

Acknowledgements

Huge thanks to imRohan for creating Pantry, which this project builds upon. It is a great project that has helped me quickly hack together prototypes and small projects. I hope Nook can help others in the same way.

License

Creative Commons Attribution-NonCommercial 4.0 International Public License (CC BY-NC 4.0)

See LICENSE for more details.