Forem: David Lange

Don't miss out!

David Lange — Fri, 07 Feb 2025 11:36:15 +0000

Alchemy Conf 2025

Miguel Palhas ・ Feb 6

Building dapps with Starknet React

David Lange — Mon, 12 Jun 2023 13:40:00 +0000

Parts of this article were originally written for The Starknet Book. Check it out for more content on Starknet development.

The good news

If you've been following Starknet's progress, you're probably aware that there has been a lot of change recently. Cairo 1 was released, and that means frontend tools need updating to keep up.

If you have experience building dapps but are new to Starknet, the good news is that you can apply plenty of that knowledge here! If you're familiar with Starknet, the good news (in my opinion) is that the changes are moving in the right direction.

Getting started

The basic tools you can use to get started are Starknet.js and get-starknet. Starknet.js is an essential low level lib, equivalent to ethers.js, whereas get-starknet handles connecting to wallets. You should definitely read Starknet.js' docs for a more in-depth understanding.

With these tools, there are basically 3 main concepts to know on the frontend:

Account

We can generally think of the account as the "end user" of a dapp, and some user interaction will be involved to gain access to it.

Think of a dapp where the user connects their browser extension wallet (such as ArgentX or Braavos) - if the user accepts the connection, that gives us access to the account and signer, which can sign transactions and messages.

Unlike Ethereum, where user accounts are Externally Owned Accounts, Starknet accounts are contracts. This might not impact your dapp's frontend, but you should definitely be aware of this difference.

async function connectWallet() {
    const starknet = await connect();
    console.log(starknet.account);
    starknet.account.signMessage(...)
}

The snippet above uses the connect function provided by get-starknet to establish a connection to the user wallet.

Provider

This one is pretty simple. The provider allows you to interact with the Starknet network. You can think of it as a "read" connection to the blockchain, with methods such as getBlock or getChainId.

Just like in Ethereum, you can use a default provider, or use services like Infura or Alchemy, both of which support Starknet.

export const provider = new Provider({
  sequencer: {
    network: "goerli-alpha",
  },
  /* rpc: {
    nodeUrl: INFURA_ENDPOINT
  } */
});

const block = await provider.getBlock("latest"); // <- Get latest block    
console.log(block.block_number);

Contracts

Of course, your frontend will likely be interacting with deployed contracts. For each contract, there should be a counterpart on the frontend. To create these instances, you will need the contract's address and ABI, and either a provider or signer.

const contract = new Contract(
  abi_erc20,
  contractAddress,
  starknet.account
);

contract.balanceOf(starknet.account.address)

If you create a contract instance with a provider, you'll be limited to calling read functions on the contract - only with a signer can you change the state of the blockchain.

Units

If you have previous experience with web3, you know dealing with units can be tricky, and Starknet is no exception. Once again, the docs are very useful here, especially this section on data transformation.

Very often you will need to convert Cairo structs (such as Uint256) that are returned from contracts into numbers:

// Uint256 shape:
// { 
//    type: 'struct', 
//    low: Uint256.low, 
//    high: Uint256.high 
// 
// }
const balance = await contract.balanceOf(address); // <- uint256
const asBN = uint256.uint256ToBN(uint256); // <- uint256 into BN
const asString = asBN.toString() //<- BN into string

And vice versa:

const amount = 1;

const amountFormatted = {
    type: "struct",
    ...uint256.bnToUint256(amount),
};

If we put it all together, calling a transfer function on a contract looks like this:


const tx = await contract.transfer(recipientAddress, amountFormatted);
//or: const tx = await contract.invoke("transfer", [recipientAddress, amountFormatted]); 

console.log(`Tx hash: ${tx.transaction_hash}`);

There are other helpful utils, besides bnToUint256 and uint256ToBN, provided by Starknet.js.

We now have a solid foundation to build a Starknet dapp! If you have a background in regular Ethereum apps, you'll notice how similar the experience is, but you're probably also wondering if there are more high-level tools out there that we can use. Well, there are!

Starknet React

Starknet React is an open-source collection of React providers and hooks for Starknet, inspired by wagmi. If you've used wagmi before, you should have a pretty good idea of what it looks like, as it aims to have a very similar API.

To explore an example project showcasing a dapp built with Starknet React, check out the starknet-demo-dapp repo.

To use Starknet React, start by installing the necessary dependencies:

yarn add @starknet-react/core starknet get-starknet

Starknet.js is an SDK for interacting with Starknet, whereas get-starknet is a package for handling wallet connections.

Then, wrap your app in a StarknetConfig component. This allows for some configuration and provides a React Context for the underlying app to be able to use the shared data and hooks. StarknetConfig receives a connectors prop that defines which wallet connection options will be available to the user.

const connectors = [
  new InjectedConnector({ options: { id: "braavos" } }),
  new InjectedConnector({ options: { id: "argentX" } }),
];

return (
    <StarknetConfig
      connectors={connectors}
      autoConnect
    >
      <App />
    </StarknetConfig>
)

Connection and account

You can now use a hook to access the connectors you defined in the config, allowing the user to connect their wallet:

export default function Connect() {
  const { connect, connectors, disconnect } = useConnectors();

  return (
    <div>
      {connectors.map((connector) => (
        <button
          key={connector.id()}
          onClick={() => connect(connector)}
          disabled={!connector.available()}
        >
          Connect with {connector.id()}
        </button>
      ))}
    </div>
  );
}

Note that there is also a disconnect function provided, in order to end the connection. Once the user has connected their wallet, you have access to the connected account through the useAccount hook. This also provides the current state of connection:

const { address, isConnected, isReconnecting, account } = useAccount();

return (
    <div>
      {isConnected ? (
          <p>Hello, {address}</p>          
      ) : (
        <Connect />
      )}
    </div>
);

Note that state values such as isConnected and isReconnecting are updated automatically, making it easier to update the UI conditionally. This is a very useful and common pattern when dealing with asynchronous processes, as it means you don't have to manually keep track of that state locally in your components.

Once the user is connected, signing messages may be done through the account value returned from the useAccount hook, or more simply through the useSignTypedData hook.

const { data, signTypedData } = useSignTypedData(typedMessage)  

return (
  <>
    <p>
      <button onClick={signTypedData}>Sign</button>
    </p>
    {data && <p>Signed: {JSON.stringify(data)}</p>}
  </>
)

You can sign an array of BigNumberish, or an object. In the event of signing an object, the data must be correctly typed, in accordance with EIP712. You can find a more in depth explanation here.

Network

Starknet React also provides hooks for interacting with the provider. For instance, useBlock fetches the latest block:

const { data, isError, isFetching } = useBlock({
    refetchInterval: 10_000,
    blockIdentifier: "latest",
});

if (isError) {
  return (
    <p>Something went wrong</p>
  )
}

return (
    <p>Current block: {isFetching ? "Loading..." : data?.block_number}<p>
)

The refetchInterval specifies how often the hook will attempt to refetch the data. Under the hood, Starknet React uses react-query for state and query management. Besides useBlock, there are other hooks that can be configured to periodically update, such as useContractRead and useWaitForTransaction.

With the useStarknet hook, it's also possible to directly access the ProviderInterface:

const { library } = useStarknet();

// library.getClassByHash(...)
// library.getTransaction(...)

Interacting with contracts

Read functions

Just like with wagmi, there is a useContractRead hook provided specifically for calling read functions on contracts. Note that this may be used even with without a connected user, as read functions don't require a signer.

const { data: balance, isLoading, isError, isSuccess } = useContractRead({
    abi: abi_erc20,
    address: CONTRACT_ADDRESS,
    functionName: "allowance",
    args: [owner, spender],
    // watch: true <- refresh at every block
});

For working with ERC20s, there is also a convenience hook - useBalance. This hook doesn't require passing in an ABI, and will return a correctly formatted balance value.

  const { data, isLoading } = useBalance({
    address,
    token: CONTRACT_ADDRESS, // <- defaults to the ETH token
    // watch: true <- refresh at every block
  });

  return (
    <p>Balance: {data?.formatted} {data?.symbol}</p>
  )

Write functions

For write functions, the useContractWrite hook is slightly different to wagmi. Due to Starknet's architecture, accounts can natively support multicall transactions. In practice, this means an improved user experience when executing multiple transactions, as you won't have to individually approve each transaction. Starknet React makes the most of this feature through the useContractWrite hook. It can be used in the following manner:

const calls = useMemo(() => {
    // compile the calldata to send
    const calldata = stark.compileCalldata({
      argName: argValue,
    });

    // return a single object for single transaction, 
    // or an array of objects for multicall**
    return {
      contractAddress: CONTRACT_ADDRESS,
      entrypoint: functionName,
      calldata,
    };        
}, [argValue]);


// Returns a function to trigger the transaction
// and state of tx after being sent
const { write, isLoading, data } = useContractWrite({
    calls,
});

function execute() {
  // trigger the transaction
  write();
}

return (
  <button type="button" onClick={execute}>
    Make a transaction
  </button>
)

In the example above, we first compile the calldata to be executed using Starknet.js's compileCalldata util. We pass the contract address, entrypoint, and calldata to the useContractWrite hook, which returns a write function we can use to actually trigger the transaction. The hook also returns the hash and state of the contract call.

Single instance of a contract

Using useContractRead and useContractWrite might not be a good fit for your use case - you might want to work with a single instance of the contract, instead of continually specifying its address and ABI in individual hooks. This is also possible throught the useContract hook:

const { contract } = useContract({
    address: CONTRACT_ADDRESS,
    abi: abi_erc20,
});

// Call functions directly on contract
// contract.transfer(...);
// contract.balanceOf(...);

Transactions

Once you have a transaction hash, you may track it's state through the useTransaction hook. This keeps a cache of all transactions, reducing duplicated network requests.

const { data, isLoading, error } = useTransaction({ hash: txHash });

return (
  <pre>
    {JSON.stringify(data?.calldata)}
  </pre>
)

Wrapping up

You can find a working example with any of these hooks implemented in this repo.

Expect more changes in the next few months, as the Starknet ecosystem continues to evolve!

Happy hacking 👋

Creating animated chickens with zdog

David Lange — Tue, 18 Apr 2023 14:34:23 +0000

Demo: https://rotating-chicken.vercel.app/
Code : https://codesandbox.io/s/rotating-chicken-pcj9w1

Some time ago I found zdog - it's a lightweight 3D javascript engine, for canvas or SVG. If you check out its site, you'll see it described as pseudo 3D. What does that mean? Basically zdog holds a model of 3D shapes, but renders everything as 2D flat shapes.

What it is not

You should know upfront that zdog has its limitations. There's no collision detection or physics, no gradients, no perspective or cameras, no lighting, and a bunch of other stuff you might want. If that's what you need, you might want to look at more powerful and real-3D engines, such as three-js.

What it is

Sounds pretty limited right? However, within these constraints, you can actually do some pretty amazing stuff with zdog, without all the overhead and complexity inherent to three-js. Just take a look at the demos page - it's got a bunch of neat examples of what zdog is best at: a flat, rounded aesthetic, with simple shapes. This makes it very designer-friendly.

It also means that it's very easy to make things actually look good. No more messing around trying to figure out if you should use MeshLambertMaterial or MeshPhongMaterial, or where to place your spot lights or area lights in relation to the scene. Just create a shape and give it a color.

Also, round shapes are actual circles - this means none of the polygon jaggedness you get in real 3D.

Ease of use

You'll find zdog is really easy to use. It has a declarative API that lets you describe the shapes you want, and add them to the scene. The example in the docs describes this well.

First, you add a canvas or svg:

<canvas class="zdog-canvas" width="240" height="240"></canvas>

Then create the shapes and add them to the scene:

// create illustration
let illo = new Zdog.Illustration({
  // set canvas with selector
  element: '.zdog-canvas',
});

// add circle
new Zdog.Ellipse({
  addTo: illo,
  diameter: 80,
  stroke: 20,
  color: '#636',
});

// update & render
illo.updateRenderGraph();

The chicken

So let's get to the chicken. I won't include all the code (you can find that in the sandbox), but I'll include the main parts. First, we need to figure out what individual shapes we need. In this case, it looks something like this:

Knowing this, we can start adding shapes:

export let model = new Zdog.Illustration({
  element: ".zdog-canvas",
  resize: true,
  rotate: { x: rotation.initialX, y: rotation.initialY },
  onResize: function (width, height) {
    this.zoom = Math.floor(Math.min(width, height) / sceneSize);
  },
});

let bodyGroup = new Zdog.Group({
  addTo:  model
});

// head
new Zdog.Hemisphere({
  stroke: 6,
  diameter: 15,
  addTo: bodyGroup,
  color: white,
  rotate: { x: Zdog.TAU / 4 },
});

// neck
new Zdog.Cylinder({
  stroke: 6,
  diameter: 15,
  length: 14,
  addTo: bodyGroup,
  color: white,
  frontFace: white,
  backface: white,
  rotate: { x: Zdog.TAU / 4, z: Zdog.TAU },
  translate: { y: 8 },
});

// beak
new Zdog.Cone({
  addTo: model,
  diameter: 4,
  length: 5.5,
  stroke: 2,
  color: yellow,
  backface: yellow,
  rotate: { y: -Zdog.TAU / 4 },
  translate: { x: 11, y: 4 },
});

// beard thing
new Zdog.Shape({
  addTo: model,
  stroke: 3.2,
  path: [
    { x: 11, y: 9 },
    { x: 11, y: 11 },
  ],
  color: red,
});

As you can see, creating shapes is easy. Besides size and color, we can set the translation and rotation. We can add shapes directly to the main model object, or add them to shapes that are then added to model.

Next, we can add the eyes:

// eyes group
let eyesGroup = new Zdog.Group({
  addTo: model,
});

// left eye
let eye1 = new Zdog.Shape({
  addTo: eyesGroup,
  stroke: 1.5,
  color: darkGrey,
  translate: { x: 8, y: -1, z: 3 },
});

// right eye
eye1.copy({
  translate: { x: 8, y: -1, z: -3 },
});

And finally the crest:

// path for each shape
const crestData = [
  {
    path: [
      { x: -4.5, y: -11 },
      { x: -5, y: -11.5 },
    ],
  },
  ...
];


let crestGroup = new Zdog.Group({
  addTo: model,
});

// create all crest shapes
crestData.forEach((item) => {
  new Zdog.Shape({
    addTo: crestGroup,
    stroke: 4.5,
    color: red,
    ...item,
  });
});

At this point, we should have a decent looking static chicken!

Animating things

Next, we can add animation. In this scene, there are 2 animations: blinking and jumping.

As per the docs, this can be done by adding a "render loop" function, that applies changes to the scene. This function runs on every frame, via requestAnimationFrame:

function animate() {
  // rotate model each frame
  model.rotate.y += 0.03;
  model.updateRenderGraph();
  // animate next frame
  requestAnimationFrame( animate );
}
// start animation
animate();

We can use the same principles for blinking.

But first, how can we visually blink? One method would be to make the eyes invisible and quickly visible again. But a slightly better way is to have a white shape just above the eyes, which we move down (covering the eyes) and then back up (revealing the eyes). Like this we get the eyelid motion, and as the shape is the same color as the chicken's head, we only see it when it's covering the eyes:

// eyelid
export let eyelid = new Zdog.Shape({
  addTo: eyesGroup,
  path: [
    { x: 8, y: -3, z: -3.4 },
    { x: 8, y: -3, z: 3.4 },
  ],
  stroke: 2,
  color: white,
});

To animate shapes, and keeping in line with zdog, I decided to use class ZAnimation:

export class ZAnimation {
  duration: number;
  frame = 0;
  force: number;
  running = false;
  onEnd?: () => void;
  apply: (val: number) => void;

  constructor(options: {
    duration: number;
    force: number;
    interval?: number;
    apply: (val: number) => void;
    onEnd?: () => void;
  }) {
    this.duration = options.duration;
    this.force = options.force;
    this.apply = options.apply;
    this.onEnd = options.onEnd;

    if (options.interval) {
      this.schedule(options.interval);
    }
  }

  schedule(interval: number) {
    setInterval(() => {
      this.running = true;
    }, interval);
  }

  start() {
    this.running = true;
  }

  stop() {
    this.running = false;
  }

  handleFrame() {
    if (!this.running) return;

    this.frame++;

    this.apply(this.force);

    if (this.frame === this.duration) {
      this.frame = 0;
      this.stop();
      this.onEnd?.();
    }
  }
}

Let's look at the class' properties:

duration: how many frames it should last;
frame: this keeps track of the animation's progress;
force: the amount that the animated shape should change in each frame;
apply: the actual transformation that will happen (such as model.rotate.y += x);
running: whether the animation is running or not. When frame equals duration, this will get set to false, as that is the animation's end;
interval: in case we want the animation to happen periodically (useful when blinking);
onEnd: optional callback that runs when the animation ends. Useful when chaining animations.

We can then use it like this:

const blinkUp = new ZAnimation({
  duration: 18,
  force: 0.1,
  apply: (val) => {
    eyelid.translate.y -= val;
  }
});

const blinkDown = new ZAnimation({
  duration: 18,
  force: 0.1,
  interval: 4000,
  apply: (val) => {
    eyelid.translate.y += val;
  },
  onEnd: () => {
    blinkUp.start();
  }
});

function animate() {
  model.updateRenderGraph();

  blinkDown.handleFrame();
  blinkUp.handleFrame();

  requestAnimationFrame(animate);
}

animate();

We create the animations, and specify that blinkDown should happen every 4 seconds, and when it ends it should call blinkUp. This is what it looks like:

What about jumping? For that we can add a couple more chained animations, and add an event listener so our chicken can jump on click:

const bounceDown = new ZAnimation({
  duration: 28,
  force: 1,
  apply: (val) => {
    model.translate.y += val;
  }
});

const bounceUp = new ZAnimation({
  duration: 28,
  force: 1,
  onEnd: () => bounceDown.start(),
  apply: (val) => {
    model.translate.y -= val;
  }
});

document.addEventListener("click", () => {
  bounceUp.start();
});

Voilá, it jumps.

Easing

Nice! We now have a blinking and jumping chicken. It's good, but you may have noticed that the jumps are kind of...bland. They look too mechanical, because the movement is linear. To make it look natural, we need to add some easing. I recommend you check out easings.net, it's an excellent resource on this subject that I used here. Besides showing what different easing functions look like, it has implementations in CSS and math functions. I actually use those exact functions in this demo.

Basically we want the force applied in each frame to change, depending on what the current frame is relative to the total duration we specified:

In the first graph, the change is linear, meaning it happens in a consistent manner over time (like our chicken right now). On the right we have an "eased" movement, where x will initially increase slowly, then more quickly in the middle of the animation, before slowing down towards the end.

We can add easing to our ZAnimation class:

class ZAnimation {
    // ...
    easing: Easing = "easeOutCirc";
    easeAcc = 0;

    constructor(options: {
        // ...
        easing: Easing;        
    }) {
        // ...
        this.easing = options.easing;        
    }

    // ...

    handleFrame() {
        if(!this.running) return;

        this.frame++;

        const value = this.calcEasedValue();
        this.apply(value);

        if (this.frame === this.duration) {
          this.frame = 0;
          this.easeAcc = 0;
          this.stop();
          this.onEnd?.();
        }
    }

    calcEasedValue() {
        const progressDecimal = (this.frame * 100) / this.duration / 100;

        let easedVal = 0;

        switch (this.easing) {
          case "easeOutCirc":
            easedVal = easeOutCirc(progressDecimal);
            break;

          case "easeOutBounce":
            easedVal = easeOutBounce(progressDecimal);
            break;
        }

        const frameEase = easedVal - this.easeAcc;
        this.easeAcc += frameEase;

        return frameEase * this.force;
    }
}

Let's break this down: when we create the animation we can specify the easing function we want (in this case there are only two options, easeOutCirc and easeOutBounce).

Then, in the handleFrame function, instead of simply using the force property, we calculate the eased force for each specific frame. For this we need to work out the current progress, from 0 to 1:

 const progressDecimal = (this.frame * 100) / this.duration / 100;

and pass that value to the easeOutCirc or easeOutBounce functions, which will in turn return a value between 0 and 1. Where are these functions? Well, I copied them from easings.net! They look something like this:

function easeInOutCubic(x: number): number {
    return x < 0.5 ? 4 * x * x * x : 1 - Math.pow(-2 * x + 2, 3) / 2;
}

Note that the value we get from the easing functions is cumulative, meaning that its output will keep increasing from 0 until it's 1 by the last time we call it, and that's not what we want. We want the incremental change for every frame. In order to do this we keep track of the accumulated amount, and subtract it from what the easing function gives us:

const frameEase = easedVal - this.easeAcc;
this.easeAcc += frameEase;

return frameEase * this.force;

Lastly, we multiply the frame's easing value by force. That's the amount by which our shape will move in each frame.

To use this updated class, we just need to add the easing type to the instances:

const bounceDown = new ZAnimation({
  duration: 32,
  force: 6.8,
  easing: "easeOutBounce",
  addTo: scene,
  apply: (val) => {
    model.translate.y += val;
  },
});

const bounceUp = new ZAnimation({
  duration: 28,
  force: 6.8,
  easing: "easeOutCirc",
  addTo: scene,
  onEnd: () => bounceDown.start(),
  apply: (val) => {
    model.translate.y -= val;
  },
});

The jumps look a lot better now.

Wrapping up

You may have noticed that in the demo the chicken also follows the mouse around. You can take a look at the code needed for that, though I'll not delve into that in this post. Who knows, we'll be back for a part II.

If you're wondering when you'll ever need a pseudo 3D chicken that jumps and blinks, I can't answer that.

But if what you need is a bit of visual flair, and don't require more advanced features, zdog can be an excellent choice. It's very easy to use and provides a set of default shapes and tools that help you get up and running very quickly. Combined with some custom animations and user interactions, you can create a delightful result.

As always, thanks for reading!

Using custom Svelte stores

David Lange — Tue, 21 Mar 2023 12:12:30 +0000

With Svelte, we get an out of the box solution for state management - stores. According to the docs, a store is any object with a subscribe, unsubscribe, and (optionally) a set method. Svelte provides the functions to easily create readable, writable, or derived stores.

At it's most simple:

const simplePizza = writable({
  ingredients: [],
  ovenTime: 0,
  status: 'idle',
});

export default simplePizza;

Then we could use it like this in a component:

<script lang="ts">
  import simplePizza from "../stores/simplePizza"

  let inputVal: string;

  function handleSubmit() {
    simplePizza.update(st => ({
      ...st,
      ingredients: [...st.ingredients, inputVal]
    }))
  }
</script>

<form on:submit|preventDefault={handleSubmit}>
  <input name="ingredient" bind:value={inputVal} />
  <button type="submit">Add</button>
</form>
<ul>
{#each $simplePizza.ingredients as ingredient}
  <li>{ingredient}</li>
{/each}
</ul>

By using the dollar sign to access the store, we're subscribing to updates in the store's value, and our component will react to any change and show the updated ingredient list (you can check the docs on the dollar sign syntax here, but it basically uses the store's subscribe function, and unsubscribes when appropriate). Outside of components, we can manually subscribe:

const unsubscribe = simplePizza.subscribe((value) => {
    // do something when there are changes
});

unsubscribe()

If you've used Svelte before, you probably already know this. What about custom stores?

Custom stores

In many cases, we're likely to need some logic around the store. For instance, we may want to control how the store is updated, without having that validation in components. This is where custom stores come in handy:

//customPizza.ts
type PizzaStore = {
  ingredients: string[];
  ovenTime: number;
  status: 'idle' | 'preparing' | 'baking' | 'ready';
};

function createPizzaStore() {
  const { set, update, subscribe } = writable<PizzaStore>({
    ingredients: [],
    ovenTime: 0,
    status: "idle"
  });

  function addIngredient(ingredient: string) {
    if (ingredient === 'pineapple') {
      throw new Error('Step away from the pizza');
    }

    update((store) => ({
      ...store,
      ingredients: [...store.ingredients, ingredient],
    }));
  }

  return {
    subscribe,
    addIngredient,
  };
}

const pizzaStore = createPizzaStore();

export default pizzaStore;

Basically, we wrap a store in a function that holds additional logic. By returning the subscribe method, we can subscribe to the store's value in our component, same as before. But we can also return other functions, defining how we want the outside world to interact with our store. You can think of it as adding methods to interact with the underlying writable store - like an API.

As you can see, stores are very flexible, and you can actually combine them with other state management libs. For that, I highly recommend you check out this post on using stores with Zustand, a very nice state management lib.

Wrapping the wrappers

We can actually extend this concept of wrapping a store. Say we have several stores, and we want them all to have some shared functionality, like syncing changes to local storage, or a remote DB. We can create a base store that receives the writable store and wrapper function we wrote previously, and passes some base functions into that wrapper:

// _baseStore.ts
interface WrapperProps<T> extends Writable<T> { 
  _syncToLocal: (key: string) => Unsubscriber;
  _set: (args: Partial<T>) => void;
}

export default function _baseStore<T, I>(
  store: Writable<T>,
  wrapperFn: (args: WrapperProps<T>) => I
): I {
  const { update, subscribe } = store;

  function _set(args: Partial<T>) {
    store.update((st) => ({
      ...st,
      ...args,
    }));
  }

  function _syncToLocal(key: string) {
    return subscribe((val) => {
      localStorage.setItem(key, JSON.stringify(val));
    });
  }

  return wrapperFn({ ...store, _syncToLocal, _set });
}

We then pass it our custom store:

// customPizza.ts
type PizzaStore = {
  ingredients: string[];
  ovenTime: number;
  status: 'idle' | 'preparing' | 'baking' | 'ready';
};

const store = writable<PizzaStore>({
  ingredients: [],
  ovenTime: 0,
  status: "idle"
});

const pizzaStore = _baseStore(
  store,
  ({ _syncToLocal, subscribe, update }) => {

    //use the received function
    _syncToLocal('myPizza');

    function addIngredient(ingredient: string) {
      if (ingredient === 'pineapple') {
        throw new Error('Step away from the pizza');
      }

      update((st) => ({
        ...st,
        ingredients: [...st.ingredients, ingredient],
      }));
    }

    return {
      subscribe,
      addIngredient,
    };
  }
);

export default pizzaStore;

As you can see, the wrapper contains all the same logic as before, except now it also receives _syncToLocal. In this way, we can move that sort of common functionality to another layer, where it can be easily reused by other stores. Let's say you also have cupcakes in your app:

const store = writable<CupcakeStore>({
  toppings: [],
  tasty: true,
});

const cupcakeStore = _baseStore(
    store, 
    ({ subscribe, _syncToLocal }) => {

      /* cupcake things */

      _syncToLocal('myCupcake');

      return {
        subscribe,
      };
});

export default cupcakeStore;

You might have noticed I also added a _set function - this is just a more concise way of using the regular update method, so instead of writing:

update((store) => ({
    ...store,
    foo: bar    
}))

we can just write:

_set({ foo: bar })

It might not seem like a huge improvement, but it's quite useful when you want to update values multiple times in a function, for example.

Instances

So far pizzaStore has been a standalone store, assuming our app will only have one pizza. However it can be useful to have instantiable stores - imagine your app allows the user to create as many pizzas as they want. There are a couple of things needed:

Allow the creation of new pizzas through pizzaStore
Store all the pizzas somewhere, so we can access them elsewhere in our app.

The first issue is pretty simple, we simply export the function. For the second issue, one approach is to use a store of stores. It's a custom store that holds an object of string: PizzaStore:

// allPizzasStore.ts
type AllPizzasStore = Record<string, PizzaStore>;

function createAllPizzasStore() {
  const { subscribe, update } = writable<AllPizzasStore>({});

  function addPizza(name: string, pizza: PizzaStore) {
    update((st) => ({
      ...st,
      [name]: pizza,
    }));
  }

  return {
    subscribe,
    addPizza,
  };
}

const allPizzasStore = createAllPizzasStore();

export default allPizzasStore;

We then add our pizzas to this underlying store whenever they are created. In order to later get the store we need, we also pass in a name key to store it with:

//pizzaStore.ts
type PizzaWritableStore = {
  ingredients: string[];
  ovenTime: number;
  status: 'idle' | 'preparing' | 'baking' | 'ready';
};

export interface PizzaStore extends Writable<PizzaWritableStore> {
  addIngredient: (ingredient: string) => void;
};

export default function pizzaStore(name: string): PizzaStore {
  const store = writable<PizzaWritableStore>({
    // writable store data
  });

  const customStore = _baseStore(
    store,
    ({ _set, _syncToLocal, update }) => {

      // .. other functions like addIngredients, etc

      return {
        ...store,
        addIngredient,
      };
    }
  );

  // add it to the store of stores
  allPizzasStore.addPizza(name, customStore);

  return customStore;
}

And then we use it:

// Allow user to create new pizzas
<button 
    type="button" 
    on:click={() => pizzaStore("pepperoni")}
>
    Add pepperoni
</button>
<button 
    type="button" 
    on:click={() => pizzaStore("tuna")}
>
    Add tuna
</button>

// And in some other component:
<script lang="ts">
    import allPizzasStore from "./allPizzasStore";

    let pep = $allPizzasStore.pepperoni
    let tuna = $allPizzasStore.tuna
</script>

<div>
    The pepperoni is {$pep.status}
    <button 
        type="button" 
        on:click={() => pep.bake()}
    >
        Bake it
    </button>
</div>

Any pizza we now create is accessible in the rest of the app via the allPizzaStore!

Wrapping up

Hopefully this demonstrates how flexible and useful stores can be in Svelte. Often, a simple store may be enough, but when necessary, we can easily adapt our stores to fit our needs.

Thanks for reading!

On demand ISR with Next.JS and Sanity

David Lange — Sat, 10 Sep 2022 16:07:36 +0000

Static sites are great, right? You get excellent performance and can make the most out of CDNs and caching. Frameworks like Next.JS have made it quite easy to create and deploy static content, and you can mix it up with SSR (server side rendering) when needed.

SSG (static site generation) has traditionally had a pretty big downside though - when you need to update something, you have to rebuild the whole thing all over again. With Next.JS though, we can mitigate that problem with ISR (Incremental Static Regenaration). Basically, ISR adds functionality to regenerate specific pages, and version 12.1 of Next brought us the highly requested on demand ISR.

This means a static Next site that fetches content from a CMS can now get updated on demand, (re)building only the parts that actually need to change.

So I decided to investigate how I could update a static site connected to Sanity CMS. For those of you who don't know, Sanity is an open-source CMS - it's flexible and pretty easy to get started with, and a great choice if you want to just host some content.

On demand revalidation

First, here's the example for ISR in the Next.JS docs:

// pages/api/revalidate.js

export default async function handler(req, res) {
  // Check for secret to confirm this is a valid request
  if (req.query.secret !== process.env.MY_SECRET_TOKEN) {
    return res.status(401).json({ message: 'Invalid token' })
  }

  try {
    // this should be the actual path not a rewritten path
    // e.g. for "/blog/[slug]" this should be "/blog/post-1"
    await res.revalidate('/path-to-revalidate')
    return res.json({ revalidated: true })
  } catch (err) {
    // If there was an error, Next.js will continue
    // to show the last successfully generated page
    return res.status(500).send('Error revalidating')
  }
}

The idea here is that you can send a request to a api/revalidate endpoint, and then call the revalidate method on the response object, passing in the path you want to update. Pretty simple right?

Sanity custom actions

So how do we call that revalidate endpoint from Sanity?

One option is using Sanity's webhooks, and there's already an article on that right here!

However, you might need a little more flexibility and control - for instance you might not want to trigger rebuilds on every single update. Or maybe you need to send requests to different frontends at different times (like when you have a staging site and a production site).

In these cases, you can use custom Sanity actions. Basically, these let you add buttons to the studio editor.

You can find a good starter on adding actions in Sanity's docs here, so I'll skip to the action itself:

export function MovieUpdateBlog(props) {
  const [status, setStatus] = useState("pending");

  const label = useMemo(() => {
    switch (status) {
      case "success":
        return "Updated";
      case "error":
        return "Something went wrong";
      default:
        return "Update blog";
    }
  }, [status]);

  if (props.type !== "movie") {
    return null;
  }

  return {
    label,
    onHandle: async () => {
      // this gets called when the button is clicked
      try {
        await revalidatePath(`/movie/${props.published.slug.current}`);

        setStatus("success");
      } catch (err) {
        setStatus("error");
      } finally {
        // Signal that the action is completed
        props.onComplete();
      }
    },
  };
}

First, we check what the document type is - in this case I only want this action to apply to "movie" documents. When the button is clicked, the onHandle function runs, and we pass in the document slug to a revalidatePath function:

async function revalidatePath(path: string) {
  try {
    const endpoint = new URL(FRONTEND_API_URL);

    endpoint.searchParams.append("path", path);
    endpoint.searchParams.append("secret", SECRET_TOKEN);

    await fetch(endpoint.href);
  } catch (err) {
    console.error(err);

    return null;
  }
}

This sends the request with the updated path to our frontend's revalidate endpoint. Success!

No, it's not so simple

In most cases one updated piece of content will require other changes elsewhere. Imagine a static site about movies - the homepage will show links to each movie's page, and on that page there's a list of the movie's cast, who also have their own page:

Fig.1: complex diagram clearly demonstrates how I could have been an architect

If we update Movie #1's name, we'll need to rebuild its page and the homepage, or else it would still show the old name. And if we update Person A's name, we need to also update the page of any movie that mentions them.

This will always depend on how your site is structured, but in this case we can deal with this logic within the action we just created:

await revalidatePaths([`/movie/${props.draft.slug.current}`, "/"]);

async function revalidatePaths(paths: string[]) {
  try {
    const endpoint = new URL(FRONTEND_API_URL);

    endpoint.searchParams.append("paths", paths.join(","));
    endpoint.searchParams.append("secret", SECRET_TOKEN);

    return fetch(endpoint.href);
  } catch (err) {
    console.error(err);

    return null;
  }
}

We're simply passing the movie's path and the / homepage path. We then have to deal with multiple paths on revalidation endpoint:

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // Check for secret to confirm this is a valid request
  if (req.query.secret !== process.env.REVALIDATION_TOKEN) {
    return res.status(401).json({ message: "Invalid token" });
  }

  try {
    const paths = (req.query.paths as string).split(",");

    for(let i = 0; i < paths.length; i++) {
      await res.revalidate(paths[i]);
    }

    return res.json({ revalidated: true });
  } catch (err) {
    // If there was an error, Next.js will continue
    // to show the last successfully generated page
    return res.status(500).send("Error revalidating");
  }
}

So what about updates to Person pages? For that, we need a new action with a little more logic:

export function OnUpdatePerson(props) {
  const [status, setStatus] = useState("pending");

  const label = useMemo(() => {
    switch (status) {
      case "success":
        return "Updated";
      case "error":
        return "Something went wrong";
      default:
        return "Update blog";
    }
  }, [status]);

  if (props.type !== "person") {
    return null;
  }

  return {
    label,
    onHandle: async () => {
      try {
        const dependantMoviesReq = await fetch(`${SANITY_ENDPOINT}?query=*["${props.id}" in castMembers[].person._ref]`);

        const { result } = await dependantMoviesReq.json();

        const movieSlugs = result.map((movie) => `/movie/${movie.slug.current}`);         
        const personSlug = `/people/${props.published.slug.current}`;

        await revalidatePath([personSlug, ...movieSlugs]);

        setStatus("success");
      } catch (err) {
        setStatus("error");
      } finally {
        // Signal that the action is completed
        props.onComplete();
      }
    },
  };

To know what movies mention the updated person, we need to query Sanity. And if you're wondering what on earth this is:

`${SANITY_ENDPOINT}?query=*["${props.id}" in castMembers[].person._ref]`

it's GROQ, Sanity's custom query language. I would probably just use GraphQL, but I thought it would be interesting to try out GROQ for this demo.

Anyway, the query returns an array of movies that refer to the person. So we just get those slugs and add the current person slug, and pass it all to revalidatePath. And now we can update all the affected pages with just one click. This kind of logic will really be specific to each case - you should also change what paths you update based on the specifc data that was changed - an update to the person's bio might not require rebuilding pages that only contain their name.

Adding new data

Does this work when creating new pages? Yes, but there's an important detail you might miss. In the movie page scenario, I'm using getStaticPaths + getStaticProps:

export const getStaticPaths: GetStaticPaths = async () => {
  const { allMovie } = await getAllMovies();

  const paths = allMovie.map((item) => ({
    params: {
      slug: item.slug.current,
    },
  }));

  return {
    paths,
    fallback: true,
  };
};

If fallback is false, it won't work - the result of getStaticPaths would be the same as at build time, when the new content didn't exist. Setting it to true ensures it gets called again.

Some things to consider

With that, we have a much smarter way of updating static pages. Still, there are some things you should consider before you start ISRing everything:

Serverless function limitations. There is usually some execution timeout on these (you can check out Vercel's here), so there's a limit to how many paths you can revalidate.
Are you using a cached endpoint? For instance, Sanity provides a live endpoint and a cdn version. If you use the cdn endpoint in your build, it might not get fresh data when revalidating.
You will need to setup CORS for your endpoint to accept the requests once it's deployed. There's a guide on how to do that here.
Don't do this in the api/revalidate endpoint:

paths.map(async (path) => await res.revalidate(path));

await Promise.all(paths);

This was my first approach, and though it worked fine in local builds, when I deployed it to Vercel it would just fail. Basically you have to revalidate the paths sequentially, so Promise.all is not an option.

Wrapping up

On demand ISR is still a pretty recent feature, and I wouldn't be surprised if it changed somewhat in the near future. For now though, it looks like it could make static sites a lot easier to manage, and cut down on build times.

Spotlight effect with JS and CSS

David Lange — Fri, 29 Apr 2022 16:00:45 +0000

Spotlight effects can be a pretty creative way of revealing content on your website. And they're surprisingly easy to create with a little JS and CSS!

The basic idea

TLDR; Use CSS radial gradient backgrounds, and then use JS to track the mouse movement and move the center of the gradient.

There are other, more complex ways of doing this - you could use canvas or external libraries - but I find the simpler approach is a good starting point and should work well enough for most use cases.

Let's get started:

#spotlight {
  position: fixed;
  opacity: 1;
  width: 100vw;
  height: 100vh;
  top: 0;
  left: 0;
  pointer-events: none;
}

<div id="spotlight"></div>

const spotlightEl = document.querySelector("#spotlight");

function handleMouseMove(event) {
    const { clientX, clientY } = event;

    spotlightEl.style.background = `radial-gradient(circle at ${clientX}px ${clientY}px, #00000000 10px, #000000ee 350px)`;
}

document.addEventListener("mousemove", handleMouseMove)

And...that's pretty much it.

The #spotlight div is positioned so that it always covers the entire viewport. We then attach an event listener to listen to the mouse's movement, and set the X and Y directly in the radial-gradient CSS value.

The #00000000 10px, #000000ee 350px part basically means we want a gradient that is transparent at it's center, and at 350px from the center is a slightly transparent black. That's how the gradient center reveals what's beneath.

Making it configurable

So far we have a basic spotlight, so let's go ahead and improve it.

We can create a Spotlight class that allows you to easily set up new spotlights and pass in some options:

toggleEl is the id of the element you want to use as a trigger to toggle the spotlight.
innerRadius and outerRadius set the spotlight size.
outerColor sets the background color (try passing in red for a truly bleeding edge experience).

The class also provides methods for switching the spolight on and off.

Making the light feel more natural

To make it a look a little more natural, there are a couple of added touches.

First, there is a slight delay in the spotlight movement. This adds a sense of weight to the light, like we're dragging it around with our mouse.

handleMouseMove(event: MouseEvent) {
    setTimeout(() => {
      this.updateEl(event.clientX, event.clientY);
    }, 50);
}

Also, you'll notice the light "pulses" slightly - continually increasing and decreasing.

But how do we get it to work?

My first instinct was to animate the gradient size, but that's not actually possible in CSS! Next I thought of somehow changing the outerRadius value in steps inside a function called in a setInterval, but that turned out to be a really stupid idea. Finally, I came up with the simple solution - animate the scale of the entire spotlight div with a CSS animation.

@keyframes pulse {
  0% {
    transform: scale(1);
  }
  100% {
    transform: scale(1.1);
  }
}

this.el.style.animation =
        "pulse 3s ease-in-out infinite alternate forwards";

This way, we don't need to touch the actual gradient, we just animate the entire "canvas", stretching the gradient in the process. I also used CSS animations for the "switching on/off" part.

Wrapping up

Obviously, you shouldn't be using spotlights in every single page (please don't!). But when used right, they're a nice way for users to feel like they're discovering some cool concealed content for the first time.

Thanks for reading!

Infinite looping React component

David Lange — Mon, 21 Feb 2022 14:21:08 +0000

Not long ago, a project I was working on came up with an unusual requirement - basically a piece of content should be infinitely sliding across the screen. It could be anything - text, images - you name it, and depending on the situation it should slide either left or right, and at different speeds. So why not create an infinite loop component?

This is more or less what it looks like.

An additional requirement was that the content should be horizontally repeated as many times as needed to cover the entire width of its parent element (most often the full width of the viewport). A large image would perhaps only need a couple of instances, whereas something smaller might need some more. I wanted to be able to just drop some content into a component, pass in the speed and direction, and let it deal with the rest.

<InfiniteLooper speed="1" direction="left">
    // the stuff you want to loop
</InfiniteLooper>

The component should be responsible for making the content repeat across the screen, as well as animating. First though, let's look at the animation.

Animating the content

What we need to do is simply translate each instance of the content 100% horizontally. When you do that with several instances side by side, the end position of each instance will be the initial position of the next one, before snapping back to its initial state. This creates the impression of continuous horizontal motion.

Remember, translating an element 100% means 100% of it's own width, not the parent element's width.

So, let's get started:

function InfiniteLooper({
    speed,
    direction,
    children,
  }: {
    speed: number;
    direction: "right" | "left";
    children: React.ReactNode;
  }) {
    const [looperInstances, setLooperInstances] = useState(1);
    const outerRef = useRef<HTMLDivElement>(null);
    const innerRef = useRef<HTMLDivElement>(null);

    return (
      <div className="looper" ref={outerRef}>
        <div className="looper__innerList" ref={innerRef}>
          {[...Array(looperInstances)].map((_, ind) => (
            <div
              key={ind}
              className="looper__listInstance"
              style={{
                animationDuration: `${speed}s`,
                animationDirection: direction === "right" ? "reverse" : "normal",
              }}
            >
              {children}
            </div>
          ))}
        </div>
      </div>
    );
  }

@keyframes slideAnimation {
  from {
    transform: translateX(0%);
  }
  to {
    transform: translateX(-100%);
  }
}

.looper {
  width: 100%;
  overflow: hidden;
}

.looper__innerList {
  display: flex;
  justify-content: center;
  width: fit-content;
}

.looper__listInstance {
  display: flex;
  width: max-content;

  animation: slideAnimation linear infinite;
}

looperInstances defines how many times the content will be repeated. To get started we can just hardcode it, but further on we'll see how to get it to work dynamically. As for CSS, we have a keyframe animation to translate from 0% to -100%, with the duration and direction set by the props we pass in.

Basically, if we're sliding from left to right, the content translates from -100% to 0%, and the opposite happens for right to left.

It might seem strange to go from -100 to 0 when we want to travel right. Why not just start at 0 and go to 100? However, if we did that, then the leftmost instance of content would just leave a blank space to its left while it translated to 100, breaking the whole impression of looping. By starting at -100, that leftmost item starts offscreen, and never leaves a blank space behind it.

Also note that the speed prop is used directly by the animation duration. This means that higher values equal slower speeds.

You may notice that the animation can be slightly janky at times in Firefox. Honestly, I haven't found a way to significantly improve this yet, though so far it hasn't proven to be too much of a problem. Either way, it's something to address eventually.

Repeating the content

Next we have to work out how many times the content needs to be repeated to cover the entire area we place it in. The basic idea is to compare the width of the innerRef and outerRef and set looperInstances accordingly. Something like this:

export default function InfiniteLooper({
    speed,
    direction,
    children,
  }: {
    speed: number;
    direction: "right" | "left";
    children: React.ReactNode;
  }) {
    const [looperInstances, setLooperInstances] = useState(1);
    const outerRef = useRef<HTMLDivElement>(null);
    const innerRef = useRef<HTMLDivElement>(null);

    const setupInstances = useCallback(() => {
        if (!innerRef?.current || !outerRef?.current) return;

        const { width } = innerRef.current.getBoundingClientRect();

        const { width: parentWidth } = outerRef.current.getBoundingClientRect();

        const instanceWidth = width / innerRef.current.children.length;

        if (width < parentWidth + instanceWidth) {
            setLooperInstances(looperInstances + Math.ceil(parentWidth / width));
        }
  }, [looperInstances]);

    useEffect(() => {
        setupInstances();
    }, []);

    return (
      <div className="looper" ref={outerRef}>
        <div className="looper__innerList" ref={innerRef}>
          {[...Array(looperInstances)].map((_, ind) => (
            <div
              key={ind}
              className="looper__listInstance"
              style={{
                animationDuration: `${speed}s`,
                animationDirection: direction === "right" ? "reverse" : "normal",
              }}
            >
              {children}
            </div>
          ))}
        </div>
      </div>
    );
  }

The setupInstances function compares the outer and inner ref widths. If the innerWidth (the width of all our content) is less than the width of the parent plus the one instance of content, that means we need to increase looperInstances. So we work out approximately how many more instances we need with parentWidth / width. We use that extra instanceWidth to provide a safety margin - without that you can sometimes have a "blank" space at the edges of the component.

What about responsiveness?

Great, so now we've got a working component! But it's not quite responsive yet. It will work fine on different screens, but what if the container element's width is increased for some reason? (Yes, by "some reason", I mostly mean developers obsessively resizing their screens).

This can be addressed by adding a resize event listener that calls setupInstances again:

useEffect(() => {
    window.addEventListener("resize", setupInstances);

    return () => {
      window.removeEventListener("resize", setupInstances);
    };
}, []);

But there's a catch: if looperInstances is incremented the new elements will be rendered, but the CSS animation will be out of sync, and you'll see things randomly overlapping or flickering. To fix this, we need to somehow reset the animation. Forcing a re-render with useState won't work. In this case I set the animation property of each instance to "none" by setting data-animate="false" on their parent, before toggling it back to "true" - resetting the animations. Just note that you need a slight delay when toggling data-animate, forcing a reflow.

function resetAnimation() {
    if (innerRef?.current) {
      innerRef.current.setAttribute("data-animate", "false");

      setTimeout(() => {
        if (innerRef?.current) {
          innerRef.current.setAttribute("data-animate", "true");
        }
      }, 50);
    }
  }

function setupInstances() {
    ...

    resetAnimation();
}

And the CSS updates:

.looper__innerList[data-animate="true"] .looper__listInstance {
  animation: slideAnimation linear infinite;   
}

.looper__listInstance {
  display: flex;
  width: max-content;

  animation: none;
}

Here I chose to set the data attribute only on a single element (.looper__innerList), changing it's children's animation via CSS. You could also manipulate each child element directly in the resetAnimation function, though personally I find the former solution simpler.

Wrapping up

And that's it! We could still take it further - we could pass in props to pause and play the animation via the animation-play-state property, or have a neater solution for the animation speed, rather than just passing in seconds for the animation-duration. Who knows, we could even add vertical animation.

Hopefully this demonstrates how you can use simple CSS animations in a React component to achieve whatever strange visual requirements your projects have.

Stay safe!