ServerlessWP
WordPress hosting is silly.
Why should a small WordPress site need a server running around the clock?
ServerlessWP [github.com/mitchmac/serverlesswp] enables low maintenance and low cost/free WordPress hosting on Vercel, Netlify, or AWS Lambda.
WordPress runs on demand in serverless functions, with a SQLite database stored in S3 or Vercel Blob. No always-on server or separate database hosting to manage.
Just want to try? Deploy on Vercel with a private Vercel Blob store for your SQLite database and media uploads. No separate database hosting or credentials to copy.
Leave the two pre-filled deploy settings as they are to enable media uploads. Once deployed, open your site’s URL and complete the WordPress setup.
Use cases
Use the familiar WordPress admin to write posts, edit pages, and upload media.
This is an experimental project, best suited to blogs, portfolios, documentation, marketing and small business sites, and dev or staging sites.
SQLite keeps setup simple for sites with light database activity, but some plugins are incompatible and competing database writes can fail. For multiple active editors, frequent form submissions, ecommerce, membership sites, or forums, use MySQL/MariaDB.
Why serverless WordPress?
- Less to maintain: no server to manage; WordPress updates arrive as pull requests you can review and merge.
- On-demand compute: run WordPress when requests need it, without keeping your own server running around the clock.
- No database server required: store SQLite in S3 or Vercel Blob.
- Branch previews: try changes with a fresh SQLite database per branch, configured automatically on Vercel.
The deploy button uses Vercel for the simplest setup, with Blob storage, CDN delivery and automatic HTTPS, and DDoS protection and firewall tools in one place. Optional Web Analytics adds visitor insights once enabled with a tracking script in WordPress. Features and usage limits vary by plan; the free Hobby plan is for personal, non-commercial projects. You can also deploy on Netlify or AWS Lambda.
Other deployment options
- Vercel with an S3 demo database: try SQLite + S3 with a temporary database that expires after a few days.
- Netlify: bring your own SQLite + S3 or MySQL database.
- AWS Lambda: deploy with the Serverless Framework using
npm install && serverless deploy.
Customization
- Plugins and themes: WordPress lives in
wp/. Add plugins towp/wp-content/plugins/or themes towp/wp-content/themes/, then commit and push to redeploy. See Keeping WordPress updated for updates through pull requests. - Uploads and generated files: media uploads and supported plugin-generated files persist in S3 or Vercel Blob. See the stream wrapper reference for file-storage limitations.
- Caching: use cache headers such as
s-maxageto enable CDN caching. See Vercel Edge Caching or Netlify Cache Headers. - Request handling: api/index.js imports the WordPress handler from serverlesswp-node. The package owns runtime behavior and request hooks. Routing is configured in vercel.json or netlify.toml.
Getting help
Start a discussion for setup help or to share your successes and ideas.
Contributing
Try ServerlessWP, report problems, and spread the word!
License
GNU General Public License v3.0
Reference
Database options
ServerlessWP supports MySQL or a SQLite database stored in Vercel Blob or an S3-compatible bucket. SQLite runs on demand, but some plugins are incompatible and competing database writes can fail. Use MySQL for sites with multiple active editors or frequent submissions. See how SQLite + S3 works.
Database selection follows this order:
- MySQL: all four connection variables below are set.
- SQLite + S3:
SQLITE_S3_BUCKETis set. - SQLite + Vercel Blob:
BLOB_STORE_ID,SQLITE_BLOB_STORE_ID, orSQLITE_BLOB_READ_WRITE_TOKENis set on Vercel. - Otherwise, the setup page appears.
SQLite + Vercel Blob
Connect a private Blob store in your Vercel project's Storage tab. Vercel supplies the store ID and OIDC authentication; each new git branch starts with its own fresh SQLite database. The deploy button handles this setup and shares the store with media uploads.
| Environment variable | Purpose / default |
|---|---|
BLOB_STORE_ID | Connected store ID; supplied by Vercel. |
SQLITE_BLOB_STORE_ID | Optional database-specific store ID; overrides BLOB_STORE_ID. |
SQLITE_BLOB_READ_WRITE_TOKEN | Optional static token instead of OIDC. The database does not use BLOB_READ_WRITE_TOKEN. |
SQLITE_BLOB_PATHNAME | Database base name; default: wp-sqlite. |
For separate database and upload stores, connect the private database store with the SQLITE environment variable prefix and the upload store without a prefix.
SQLite + S3
Create a private S3-compatible bucket (including Cloudflare R2), preferably near your functions. Works on Netlify, AWS, and Vercel.
| Environment variable | Purpose |
|---|---|
SQLITE_S3_BUCKET | Bucket name. |
SQLITE_S3_API_KEY | API access key. |
SQLITE_S3_API_SECRET | API secret key. |
SQLITE_S3_REGION | Bucket region. |
SQLITE_S3_ENDPOINT | Optional custom endpoint, e.g. for Cloudflare R2. |
MySQL database option
Create a MySQL-compatible database and set the following; wp-config.php connects automatically. TiDB is one hosted option.
| Environment variable | Purpose |
|---|---|
DATABASE | Database name. |
USERNAME | Database user. |
PASSWORD | Database password. |
HOST | Database host. |
TABLE_PREFIX | Optional table prefix. |
Media uploads on Vercel Blob
The stream wrapper persists uploads in object storage because local writes do not survive redeploys. The deploy button enables it; for an existing project, configure:
| Environment variable | Purpose / default |
|---|---|
SERVERLESSWP_STREAM_PROVIDER | vercel-blob for Vercel Blob, or s3 for a bucket. |
SERVERLESSWP_STREAM_VERCEL_ACCESS | private or public; must match the store's access setting. |
SERVERLESSWP_STREAM_VERCEL_STORE_ID | Optional store ID; falls back to BLOB_STORE_ID, then SQLITE_BLOB_STORE_ID. |
SERVERLESSWP_STREAM_CACHE_CONTROL | Served-file cache header; default: public, max-age=3600, s-maxage=86400. |
SERVERLESSWP_STREAM_CDN_BASE_URL | Optional public Blob CDN URL to serve files directly. |
Vercel OIDC authenticates writes without manually added credentials. Private uploads are served through the function and cached at the edge. Plugins, themes, mu-plugins, and languages stay local; .php, .log, .sqlite, and .htaccess files are never routed. See the stream wrapper README for all settings, S3 configuration, and limitations.
Keeping WordPress updated
The Update WordPress GitHub Action checks daily and opens pull requests; merging them redeploys your site. Enable it in your repository:
- Settings → Actions → General → Workflow permissions → Allow GitHub Actions to create and approve pull requests. Without this, the action still pushes a branch for you to open a PR manually.
- Actions → Update WordPress → Enable workflow, if disabled. GitHub disables scheduled workflows after 60 days without a push. Run workflow starts a check manually.
| Component | Update behavior |
|---|---|
| WordPress core | Replaces files verified against wordpress.org checksums; skips edited or deleted files and preserves your plugins, themes, uploads, and wp-config.php. The PR lists skipped and modified core files. |
| Bundled plugins | Separate PR; updates only plugins whose entire installed release matches wordpress.org checksums. Modified, premium, custom, and other unverified plugins are skipped and listed. |
| SQLite Database Integration | Mirrors its GitHub default branch; review the PR diff. Updates remove files you add inside this plugin's directory, so keep custom code in a separate plugin. |
| Themes | Reports available updates for manual installation; no automatic updates because wordpress.org provides no theme checksums. Themes bundled with WordPress are excluded from the report and covered by core updates. |
Check without changing files:
Keeping the framework updated
Framework code and PHP implementations ship in the serverlesswp npm dependency.
Your wp/ files remain site-owned: add plugins, MU plugins and themes normally.
The committed ServerlessWP MU-plugin loaders explicitly import the installed
package. wp-config.php remains complete and editable in your site, with no
package import. Installation and builds do not generate or replace files under
wp/; wp-config.php stays entirely site-owned.
This repository is the source of truth for the handlers, MU-plugin loaders, deployment configuration and workflows. Bring changes to those files into your site through Git. The npm package contains the framework implementation, without scaffold templates or configuration migration tooling.
Update the package and lockfile, test and deploy.
