tiny frontend

Deploy your own

If you like this architecture and want to deploy your own, this guide is for you! You mostly to deploy 3 things:

  • A tiny frontend api to deploy your bundle to.

  • A tiny frontend of your own to deploy to that api.

  • The contract npm package to publish to an npm registry to consume your tiny frontend at runtime.

WARNING

This section will make much more sense if you have read the Architecture one before!

Deploying the tiny frontend Cloudflare api

This is where your tiny frontend bundles will be deployed to.

  1. If you don't have one already, setup a Cloudflare accountopen in new window.

  2. Fork the tiny frontend api cloudflareopen in new window repository on GitHub.

  3. Enable GitHub actions for your forked repo under the Actions tab.

  4. Add two new secrets in your forked GitHub repository secretsopen in new window:

  5. Clone your forked GitHub repository locally.

  6. Create a KV namespaceopen in new window in Cloudflare to deploy your tiny frontends to, the name doesn't matter.

  7. Edit wrangler.toml and set the TinyFrontendKv id value to the KV namespace you've created above. (You can ignore the preview_id for now.)

  8. Commit and push your changes to main, this will trigger the Deploy Cloudflare Worker GitHub action.

You should see the worker appear in your Cloudflare workers dashboardopen in new window, along with its URL 🎉 .

Deploying the example tiny frontend

This is your actual tiny frontend you will deploy to the tiny frontend api above.

Setting up the repository

  1. Fork the tiny frontend exampleopen in new window repository on GitHub.

  2. Enable GitHub actions for your forked repo under the Actions tab.

  3. Add three new secrets in your forked GitHub repository secretsopen in new window:

  • CF_ACCOUNT_ID you can find it in the workers section of your Cloudflare dashboardopen in new window.

  • CF_API_TOKEN this can be the same as the one created for the tiny frontend Cloudflare api above. If you don't have it anymore, you can follow the same steps again to create a new one.

  • CF_KV_NAMESPACE_TINY_FRONTEND set it to the id of the KV namespace you created before.

  1. Clone your forked GitHub repository locally.

TIP

In the future, I'd like to have some kind of generator for this step instead of relying on forking the example.

Making changes to the tiny frontend

Sure, my example component is ✨ Amazing ✨, but you probably want something different. Let's see how to change things.

Running it locally

To let you work on your tiny frontend independently of any host, you can use the included viteopen in new window dev server:

cd app
npm i
npm run dev
1
2
3

This starts a small dev server on http://localhost:3000open in new window with app/index.html and app/src/main.tsx.

Changing the props

In contract/src/props.ts, change ExampleTinyFrontendProps to whichever props your component will need.

Then change the dev app in app/src/App.tsx to pass the required props.

WARNING

Changing props is usually a breaking change.

If you have already published a version of your contract, you should also update the version of your tiny frontend in contract/package.json.

This will ensure your new app with breaking changes doesn't get pulled by consumers of the current contract, who might not be compatible at runtime with your change.

Changing the implementation

In app/lib/index.tsx, you can change the implementation of your component.

Deploying the app

Once you're happy with your frontend, simply commit and push. This should trigger the Deploy Tiny Frontend GitHub action, and deploy your frontend to your tiny api for your contract version.

Consuming the contract locally

If you don't want to publish the contract npm package to a npm repository to try it out, you can consume it locally using yalcopen in new window.

First, "publish" your contract on your machine:

cd contract
npm i
npm run build
npx yalc publish
1
2
3
4

TIP

This won't publish it online, only locally on your computer!

Create an example Remix app, or clone the example host remix oneopen in new window.

Install your local contract package:

cd my-remix-app
npx yalc add @tiny-frontend/example-tiny-frontend-contract
npm i
1
2
3

You can now use your tiny frontend in your Remix app by pointing to your deployed tiny api:

// ⚠️ Notice the `/api` at the end of that URL!
loadExampleTinyFrontendClient("https://YOUR-CLOUDFLARE-WORKER.workers.dev/api")
1
2

Publishing the contract

The contract can be deployed like any regular npm package.

The example tiny frontend include a Publish GitHub action that publishes to the public npm repository when you create a GitHub release.

Checkout GitHub actions documentationopen in new window on how to publish to other npm repositories.