DEV Community: James Sinkala

Create a distributed API for your e-commerce store using Cloudflare and Turso

James Sinkala — Tue, 19 Sep 2023 20:16:01 +0000

In the world of eCommerce, every millisecond of latency matters. Creating a fast, reliably performant solution for end users can help drive sales. Fortunately, it’s easier than ever to do this.

In this blog post, we are going to learn how to create a distributed (edge) API for an e-commerce store using Cloudflare Workers and Turso.

We’ll also be using Drizzle as the ORM (Object-relational Mapping) tool for our project, which simply means it will handle the generation and migration of the project’s database schema and help build queries.

While composing the REST API with this stack, Cloudflare Workers and Turso, we expect the compute and data to be as close as possible (at the edge) to the API consumers. This will facilitate low latency from most parts of the world.

The API we are going to build is the data source for a “Mugs Store” e-commerce store. Ideally, you have several endpoints and data models in a complete store, but for brevity, we are going to work with two data models, “Mugs” as the products model and “Categories”. These are the models that our API endpoints will be based on.

To see the complete source code of the e-commerce API being built visit the repo on GitHub.

t visit the repo on GitHub.

Prerequisites:

Node.js and npm: You need to have Node.js and npm installed in your machine to use the Cloudflare workers and Drizzle CLI tools.
An installation of the Turso CLI.
A Cloudflare account: If you do not have one, register for a Cloudflare account to work with and deploy Cloudflare Workers projects.

Creating a new Cloudflare workers project

To get started with a new Cloudflare workers project run:

npm create cloudflare

You’ll be asked some questions to define the app you are building with Cloudflare, respond using the following template.

~ npm create cloudflare
using create-cloudflare version 2.0.9
╭ Create an application with Cloudflare Step 1 of 3
│
├ Where do you want to create your application?
│ dir mug-store-api
│
├ What type of application do you want to create?
│ type "Hello World" script
│
├ Do you want to use TypeScript?
│ typescript yes
│
├ Copying files from "simple" template
│
├ Do you want to use git?
│ git yes
│
╰ Application created
╭ Installing dependencies Step 2 of 3
│
├ Installing dependencies
│ installed via `npm install`
│
├ Committing new files
│ git initial commit
│
╰ Dependencies Installed
╭ Deploy with Cloudflare Step 3 of 3
│
├ Do you want to deploy your application?
│ no deploying via `npm run deploy`
│
├ APPLICATION CREATED Deploy your application with npm run deploy
│
│ Run the development server npm run start
│ Deploy your application npm run deploy
│ Read the documentation https://developers.cloudflare.com/workers
│ Stuck? Join us at https://discord.gg/cloudflaredev
│
╰ See you again soon!

On completion, cd into the project’s directory and you should expect the project to contain the following directory structure.

.
├── node_modules
├── package-lock.json
├── package.json
├── src
│ └── worker.ts
├── tsconfig.json
└── wrangler.toml

Delete all the commented-out bindings information inside the "wrangler.toml" and "src/worker.ts" files as we won’t be using them.

If it’s the first time you are working on a Cloudflare project, you’ll need to authenticate the project’s workspace to be able to create secrets and eventually deploy the project on Cloudflare.

Follow these steps if this statement applies to your project.

First, authenticate the project’s workspace by running npx wrangler login. This should open a new tab on your browser and you should see the request demonstrated below.
First, authenticate the project’s workspace by running npx wrangler login. This should open a new tab on your browser and you should see the request demonstrated below.

In the next section, we’ll be creating a Turso database and adding its database URL and authentication token to the Cloudflare Workers bindings passed as the second argument of the fetch function inside the worker’s default export found inside "src/workers.ts".

Creating a Turso database

You need to log in to the Turso CLI before you can use it to create and manage databases. Run the following command to do so.

turso auth login

This will open up a browser tab and ask you to authenticate via GitHub. If you are doing this for the first time, you will need to give the Turso application permission to use your account. Grant Turso the permissions needed to proceed.

After authentication, run the following command to create a new database.

turso db create mugs-store-api

The above command will create a new database named mugs-store-api in the location closest to you in the currently supported locations.

To get the database details we’ll need to pass to the worker’s fetch function, and run the following two commands.

# Get the database url
turso db show --url mugs-store-api

# Create a database authentication token
turso db tokens create mugs-store-api

Copy the results of the above command and store them as we’ll be using them in the proceeding instructions.

For the database URL, add a [vars] section inside the workers configuration file "wrangler.toml" adding it as the environment variable TURSO_DB_URL.

[vars]
  TURSO_DB_URL = "<OBTAINED-DB-URL>"

Since the authentication token is a sensitive variable, add it as a workers secret environment variable TURSO_DB_AUTH_TOKEN by running the following command:

npx wrangler secret put TURSO_DB_AUTH_TOKEN

You’ll be prompted to provide the secret value afterwards, paste the Turso database auth token obtained in the previous step.

Next, add the environment variable keys to the worker’s Env interface inside the "/src/worker.ts" file as follows:

export interface Env {
  TURSO_DB_AUTH_TOKEN?: string;
  TURSO_DB_URL?: string;
}

When you run npm run dev at this stage you will still see a “Hello World” message displayed since that’s what the fetch function is currently returning as a response.

Let’s change that and have JSON responses returned to respective HTTP requests made to our API.

Handling endpoints with a router

To streamline the API endpoints we’ll need to use a router, and in this example, we are going to use the JavaScript micro-router, itty-router.

To install it run the following command:

npm install itty-router

Back in the worker file, add the router and its type to the Env type we added the database bindings to earlier.

import { RouterType } from 'itty-router';
export interface Env {
  …
  router?: RouterType;
}

Let’s create a router-initiating function that will handle our endpoints and return the itty-router instance.

import { Router, type RouterType } from 'itty-router';

export function buildIttyRouter(env: Env): RouterType {
  const router = Router();
  router.get('*', () => json('Hi World!'));

  return router;
}

Update the fetch function inside the worker’s default export to initiate and use the router to handle received requests.

async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
  if (env.router === undefined) {
    env.router = buildRouter(env);
  }
  return env.router?.handle(request);
}

Now, when visiting localhost:8787 you should see a JSON response with the details “Hello there!”. This means that our router is successfully handling our worker requests, the next step would be adding endpoints that will be responding to respective HTTP requests made to our API.

But, before that, you’ll first need to define the data models for our API, generate their schemas, and migrate them to our database. We are going to do this with the help of Drizzle.

Setting up Drizzle as the ORM tool for the project.

To use Drizzle in the project you’ll need to install the following packages.

npm install drizzle-orm @libsql/client
npm install --save-dev drizzle-kit drizzle-zod tsx dotenv

The drizzle-orm package is used to model data schema, migrate them, connect to our database, and build queries, while the drizzle-kit package is a CLI tool used to generate migration files. The drizzle-zod package will assist with validating the JSON data being submitted to our endpoints. And lastly, we use the tsx module to execute the typescript code.

Create and generate database schemas using Drizzle.

Create a "/drizzle" directory at the root of the project. Inside it, add a "/schemas.ts" file and add the Drizzle schemas for our database. The following is the schema for the categories table for this project.

To see the full Drizzle schema for this project, open this file.

import {
  sqliteTable,
  text,
  uniqueIndex,
} from 'drizzle-orm/sqlite-core';
import { createInsertSchema, createSelectSchema } from 'drizzle-zod';

export const categories = sqliteTable(
  'categories',
  {
    id: text('id').primaryKey(),
    name: text('name'),
  },
  (categories) => ({
    nameIdx: uniqueIndex('name_idx').on(categories.name),
  }),
);
export const insertCategorySchema = createInsertSchema(categories);
export const selectCategorySchema = createSelectSchema(categories);

Let’s create a script that will handle the migrations generation using the Drizzle CLI, using the created schema as input. Inside package.json add the following ”generate” script.

"scripts": {
  ...
  "generate": "npx drizzle-kit generate:sqlite --out ./drizzle/migrations --breakpoints --schema=./drizzle/schema.ts",
  ...
}

We are using the Drizzle CLI to generate SQL migrations in the above script passing "./drizzle/migrations" as the output directory for the generated migration files.

Run npm run generate to see the migrations generated and placed inside the selected directory.

On successful schema generation, you should see the following output on the terminal.

2 tables
categories 2 columns 1 indexes 0 fks
mugs 8 columns 5 indexes 1 fks
```



### Migrating database schemas with Drizzle

To migrate the generated schema to our database we need to add the migration code. Create a "migrate.ts" file under the "/drizzle" directory and add the following code inside it.



```ts
import 'dotenv/config';
import { createClient } from '@libsql/client';
import { drizzle } from 'drizzle-orm/libsql';
import { migrate } from 'drizzle-orm/libsql/migrator';

const client = createClient({
  url: process.env.TURSO_DB_URL as string,
  authToken: process.env.TURSO_DB_AUTH_TOKEN as string,
});

const db = drizzle(client);

async function main() {
  await migrate(db, {
    migrationsFolder: './drizzle/migrations',
  });
}

main()
  .then((res) => {
    console.log('Tables migrated!');
    process.exit(0);
  })
  .catch((err) => {
    console.error('Error performing migration: ', err);
    process.exit(1);
  });
```



In the `migrate()` function above we pass the output directory of our generated migrations as the second argument so that Drizzle’s libSQL migrator knows the location of the migrations.

Since the migration process is done locally, we can’t use the environment variables added to the Cloudflare worker to handle the connection to our Turso database.

To make sure the data migration works, provide the database environment variables required in the above Node.js migration environment by adding a ".env" file with the following keys. Assign them with the database variables we acquired earlier.



```txt
TURSO_DB_URL=<DB-URL>
TURSO_DB_AUTH_TOKEN=<AUTH-TOKEN>
```



To streamline the execution of schema migrations add the following script in "package.json".



```json
"scripts": {
  ...
  "migrate": "tsx drizzle/migrate"
  ...
}
```



After having set this up, you can now perform database migrations by running `npm run migrate`.

Run `turso db shell mugs-store-api .tables` to validate if the tables were added to your Turso database.

If you updated the schema to reflect the code in the repository, you should expect the following tables to be listed.



```txt
__drizzle_migrations
categories
mugs
```



*Note*: The repo on GitHub contains the code to [some demo data that can be seeded](https://github.com/turso-extended/api-turso-cf-workers/blob/master/drizzle/seed.ts) to the database.

## Create and respond to API endpoints

To make our API functional, there’s a need for it to respond to HTTP requests with the expected data. To do that we need to transact with Turso and get or submit data into the database depending on the nature of the requests.

Let’s create a database client-building function that returns a libSQL (Turso) client wrapped with Drizzle as the query builder.

Add the following function to the worker file.



```ts
import { createClient } from '@libsql/client/http';
import { drizzle, LibSQLDatabase } from 'drizzle-orm/libsql';

function buildDbClient(env: Env): LibSQLDatabase {
  const url = env.TURSO_DB_URL?.trim();
  if (url === undefined) {
    throw new Error('TURSO_DB_URL is not defined');
  }

  const authToken = env.TURSO_DB_AUTH_TOKEN?.trim();
  if (authToken === undefined) {
    throw new Error('TURSO_DB_AUTH_TOKEN is not defined');
  }

  return drizzle(createClient({ url, authToken }));
}
```



Next, initiate a database client by adding the following code inside the `routeBuilder()` function we created earlier.



```ts
function buildIttyRouter(env: Env): RouterType {
  const db = buildDbClient(env);
  // router code
}
```



Now, we can proceed with creating the API endpoints.

### Add API endpoints to handle basic CRUD requests

Before adding the endpoints install the [uuid package](https://www.npmjs.com/package/uuid) which we are using to generate unique IDs for our table rows within this project.



```sh
npm install uuid
```



Then, import it at the top of our worker file.



```ts
import { v4 as uuidv4 } from "uuid";
```



For the proceeding endpoints code make sure to update the required imports.



```ts
import { error, IRequest, json, Router, RouterType, withParams, } from 'itty-router';
```



Starting with basic GET requests, create two endpoints, one that handles the request to fetch all mugs and the second that returns a mug based on the provided `id`.



```ts
function buildIttyRouter(env: Env): RouterType {
  const router = Router();
  const db = buildDbClient(env);

  router
  .get('/mugs', async () => {
    const mugsData = await db.select().from(mugs).all();
    return json({
      mugs: mugsData,
    });
  })
  .get('/mug/:id', async ({params: { id }}) => {
    if (!id) {
      return error(422, 'ID is required');
    }
    const mugData = await db.select().from(mugs).where(eq(mugs.id, id)).get();
    return mugData
      ? json({
        mug: mugData,
      })
      : error(404, 'Mug not found!');
    })
// subsequent endpoint routes
}
```



For data submission POST requests, the following is the code to the endpoint that handles the creation of a new category.



```ts
  // previous endpoint routes
  .post('/category', async (request: IRequest) => {
    const jsonData = await request.json();
    console.log('HERE 1');
    const categoryData = insertCategorySchema.safeParse({
      id: uuidv4(),
      ...(jsonData as object),
    });
    if (!categoryData.success) {
      const { message, path } = categoryData.error.issues[0];
      return error(path.length ? 422 : 400, `[${path}]: ${message}`);
    }

    const newCategory = await db
      .insert(categories)
      .values(categoryData.data)
      .returning()
      .get();

    return json(
      { category: newCategory },
      {
        status: 201,
      },
    );
  })
```



For the data update PATCH requests for categories based on the provided `id`, add the following endpoint.



```ts
 // previous endpoint routes
  .patch('/category/:id', async (request) => {
    const { id } = request.params;
    if (!id) {
      return error(422, 'ID is required');
    }

    const jsonData: { name: string } = await request.json();

    if (!Object.keys(jsonData).length){
      return error(400, 'No data is being updated!');
    }
    const category = await db
      .update(categories)
      .set(jsonData)
      .where(eq(categories.id, id))
      .returning()
      .get();

    return json({ category });
  })
```



And lastly, for the DELETE requests to mug items using the item `id`s, add the following endpoint.



```ts
.delete('/mug/:id', async ({params: { id }}) => {
  if (!id) {
    return error(422, 'ID is required');
  }
  const mugData = await db
    .delete(mugs)
    .where(eq(mugs.id, id))
    .returning()
    .get();
  return json({
    mug: mugData,
  });
})
```



For the remaining endpoints for the Mug Store API, view the [router function code](https://github.com/turso-extended/api-turso-cf-workers/blob/master/src/worker.ts#L41-L244) inside the worker file on the GitHub repository.

Test to see if every endpoint works as intended and perform fixes where necessary.

Next, we’ll be deploying our REST API to the Cloudflare network.

## Deploying the API to the Cloudflare network

If your project was scaffolded with the deprecated `”wrangler publish”` as the workers deploy script on "package.json" update it to use the updated `”wrangler deploy”` command.

You can then deploy the Mug Store e-commerce API to Cloudflare’s distributed network by running the following command.



```ts
npm run deploy
```



This command should log details along the following lines when the worker project is deployed successfully.




```txtYour worker has access to the following bindings:
- Vars:
- TURSO_DB_URL: "libsql://mug-store-api-xinnks.turso.io"
Total Upload: 272.46 KiB / gzip: 50.44 KiB
Uploaded the-mugs-store-api (4.92 sec)
Published the-mugs-store-api (7.13 sec)
https://the-mugs-store-api.xinnks.workers.dev
Current Deployment ID: …
```



You can now access your distributed e-commerce API from whatever head you choose ranging from web, mobile, to desktop projects using the published URL provided above.

> You can use the URL in the above deployment log to test the REST API routes provided in this blog post. This distributed API comprises Turso database instances hosted in the following three locations — Denver (US), Johannesburg (South Africa), and Paris (EU).

For more information regarding the stack used in this blog post, visit the following links:

- [Turso docs](https://docs.turso.tech)

- [Cloudflare workers docs](https://developers.cloudflare.com/workers/get-started/)

- [Drizzle docs](https://orm.drizzle.team/docs/quick-start)

- [Itty-router docs](https://itty.dev)

If you enjoyed this article and would like to get updates on more content like this, you can follow me on X (previously Twitter) — [@xinnks](https://twitter.com/xinnks). Create a distributed API for your e-commerce store using Cloudflare and Turso

A/B testing use case with Turso

James Sinkala — Thu, 13 Jul 2023 11:45:18 +0000

A/B testing is a user experience research methodology that consists of a randomized experiment that usually involves two variants A and B. A/B tests are a methodology that help test hypotheses that creators might have concerning user behavior to new features.

In this blog, we are going to implement A/B testing on the edge using Next.js’s edge middlewares, Turso, the edge database based on libSQL, and GrowthBook, an open-source feature flagging and experimentation platform that also supports implementation at the edge. We are using Turso as the database in this setup to leverage its distributed nature which will facilitate quick user data retrieval speeds.

We are going to use the project that’s found on this GitHub repo to demonstrate the implementation of an A/B test using the above stack.

The project in question is a website that lists the top frameworks for developing for the web.

New contributions to the list are made inside the “/add-new” page, but, before you can contribute to the framework list, you need to register for an account.

Say we’ve seen a low number of contributions on this website and we would like to incentivise users into submitting more contributions by displaying the message “Submit a framework to win a prize!”.

So, our A/B testing hypothesis would be along the lines of, “adding an incentive message on the framework contribution page would lead to an increase in submissions”.

Our A and B test choices will be either displaying the incentive message or not respectively, depending on a boolean feature flag that we’ll define which determines whether the incentive message gets shown. And, the target audience for our experiment will be users that have never made framework submissions before.

Let’s go ahead and implement the A/B test on our project to test our hypothesis

Getting started

First, fork the project from the provided GitHub repository and clone it to your local environment.

Next, install the project’s dependencies by running npm install. Rename the env.example file at the root of the project to env.local.

Setting up Turso

The project’s README file provides steps for setting up Turso. After following them, you’ll end up with a database with three tables — frameworks, users, and contributions, with the frameworks table populated with some initial data.

You’ll also get instructions on how to obtain the database URL and token which you’ll use to populate the NEXT_TURSO_DB_URL and NEXT_TURSO_DB_AUTH_TOKEN environment variables inside the project’s env.local file.

Setting up GrowthBook

You can either self-host GrowthBook or use the cloud version, we’ll use the latter for simplicity.

Head over to growthbook.io and create an account.

Next, we’ll follow along the onboarding process as follows

Add a feature: Fill in “add-contribution-incentivizing-message” as the feature key and leave the rest of the fields as they are. You’ll notice that we’re leaving the value type as a Boolean, meaning that the feature is either on or off. The default value when enabled lets us either force an on or off when the feature is enabled in our experiment.
Install an SDK: On this step you’ll be tasked with creating your first SDK connection. First, fill in “AB Test Demo” as the name of the app, then, select Node.js as the tech-stack that applies for our project.

After clicking on the “Continue” button, you’ll be provided with GrowthBook’s starter code for Node.js and some config keys.

Use these keys to populate the GB_API_ENDPOINT, GB_API_HOST, and GB_CLIENT_KEYenvironment variables within the env.local file.

Finally, scroll to the bottom of this page and click “Skip Step” to skip checking the connection.

We’ll also skip the “Add Data Source” step as it isn’t the focus of this post. In short, this is the step where you get to integrate your analytics infrastructure since GrowthBook doesn’t store a copy of your data. You can even add a custom data source.

We’ll also skip setting up metrics, open this link to find more information on them.

Access the menu and go to the All Features page. You should see the feature we just added listed here. Click on it to open the feature configuration page.

Setting up A/B experiments on GrowthBook

To set up an experiment on the feature we just created, click on the “Add Experiment Rule” button under A/B Experiment.
Populate the resulting form’s fields as follows.

Take note of three important points in this A/B experiment configuration.

First, the previousContribution is equal to 0 targeting condition which means that we’ll only apply the A/B test when the test for this attribute is successful. In short, the target of this experiment is those users that have never made contributions before.

Second, the tracking key add-contribution-incentivizing-message which GrowthBook will use as a unique identifier for this experiment in tracking impressions and analyzing results.

And lastly, the id selected as the input for the Assign value based on attribute field, which GrowthBook will hash together with the tracking key to determine which variant of our experiment to assign.

After clicking “Save”, you’ll see a notification on top of the page asking you to review and publish the added changes.

Review and publish the added changes.

Configure GrowthBook on Next.js’ edge middleware

Back in our project, install the GrowthBook SDK by running the following command.

npm install @growthbook/growthbook

Open the /middleware.ts file found at the root of the project.

You’ll notice that this is an edge middleware with the file runtime set up as experimental-edge.

Since we’ll be conditionally targeting routes inside the middleware, remove the hardcoded path matcher, and instead add a conditional statement to refactor the logic that delivered the city’s name to the site’s home page.

if(url.pathname === "/"){
  url.searchParams.set('city', city)
}

Since we’ll be targeting the /add-new route, add its respective condition.

if(url.pathname.startsWith('add-new'){
  // A/B test implementation
}

All of the following A/B testing implementations will go inside this conditional block.

The first step is checking whether the userId is provided, which per the set-up of our project’s authentication system it’s a cookie with the name userId.

const userId = req.cookies.get('userId')?.value;
if(!userId){
  url.searchParams.set('error', 'Log in first')
  return NextResponse.redirect(url.origin + '/log-in')
}

Next, get the value of the previousContributions attribute we had set as a target condition while configuring our A/B test rules from the Turso database by counting the number of contributions an authenticated user has made to the database.

const user = await tursoClient.execute({
  sql: "Select count(*) as total_contributions from contributions where user_id = ?",
  args: [userId]
});

const previousContributions = user.rows[0]["total_contributions"];

Afterwards, we initialize a GrowthBook instance, using the environment variables we stored above and all the necessary attributes that facilitate the triggering of our A/B test.

const gB = new GrowthBook({
  apiHost: process.env.GB_API_HOST,
  clientKey: process.env.GB_CLIENT_KEY,
  enableDevMode: true,
  attributes: {
    userId,
    city,
    loggedIn: !!userId,
    previousContributions: previousContributions || 0,
    country: country,
    url: url.href
  },
  // Only required for A/B testing
  // Called every time a user is put into an experiment
  trackingCallback: (experiment: any, result: any) => {
    // TODO: Use your real analytics tracking system
    console.log("Viewed Experiment", {
      userId,
      experimentId: experiment.key,
      variationId: result.key
    });
  }
});

The attributes required in the above code for our A/B test to be triggered are previousContributions and id, all the others are included for demonstrational purposes which might apply in other tests. The id is mainly required for tracking users to determine what variants of our experiment they get to see just as explained before.

trackingCallback() is the callback function that triggers the provided analytics tracking service (which we haven’t configured in this example) that gets called whenever a user is put into an experiment. This will help us track the state of our experiments. In our code, we just emulate this by logging out the experiment information.

The step that follows is the loading of the GrowthBook features which is done by calling the localFeatures() instance function.

await gB.loadFeatures({ autoRefresh: true });

And finally, we check whether the test is enabled or not for the authenticated user by passing the feature key on the isOn instance function.

We use this information to determine whether to show the feature we are testing or not on the client side of our application. In this project, we do so by passing a searchParam to the client that informs it what to do.

if(gB.isOn("add-contribution-incentivizing-message")) {
  url.searchParams.set('show_contribution_incentive_message', "Enabled!")
} else {
  url.searchParams.set('show_contribution_incentive_message', "Disabled!")
}

Displaying features on the client

After having determined the variant of the test to be displayed to the current user, we finally apply the necessary logic on the client side resulting in either displaying the feature or not.

In our project, we need to check the value of the show_contribution_incentive_message searchParam passed from the edge on the target page, in this case — /add-new, and displaying the feature depending on the provided state.

const {error, message, show_contribution_incentive_message} = request.searchParams;

return (
<!--HTML markup →
  {
   show_contribution_incentive_message.includes("Enabled") && <div className='bg-blue-200 text-blue-800 p-2 w-full'>
    Submit a framework to win a prize!
  </div>
  }
)

Since we are observing first time submissions, we should add logic to theframework submissions endpoint that records all the submissions made by the target audience of our A/B test.

if(add.lastInsertRowid){
  const contributions = await tursoClient.execute({
    sql: "Select count(*) as total_contributions from contributions where user_id = ?",
    args: [userId]
  });

  const previousSubmissions = contributions.rows[0]["total_contributions"];

  await tursoClient.execute({
    sql: "insert into contributions(framework_id, user_id) values(?, ?)",
    args: [add.lastInsertRowid, userId]
  })

  if(!previousSubmissions){
    // TODO: Trigger hypothesis supporting event on your real analytics tracking system
    console.log("Made Contribution", {
      userId: userId,
    });
  }
}

Depending on the data collected over a specific period we will be able to eventually have statistical data that would either back, disqualify, or render our hypothesis inconclusive. We can then make data-backed decisions on the implementation of features.

This completes the implementation of the A/B test using GrowthBook with data stored in Turso on a Next.js edge application.

To see the final version of this project with the A/B test logic implemented, open the edge-ab-testing branch on the repository.

You can proceed to register some users and test to see if the test works as implemented.

Here is a simple demonstration.

Create a shopping cart using Qwik and Turso

James Sinkala — Tue, 11 Jul 2023 12:21:53 +0000

A shopping cart is an e-commerce software that enables visitors to purchase items on the web. It is one of the most prevalent programs that users of the web come across. If your company sells things online, it’s likely that you’ve purchased, built, or are subscribed to such a service.

Shopping carts facilitate e-commerce and are of significant importance to merchants since they automate product listing, the verification of payment cards, the storage and management of customer details and their orders, and lastly, checking out. Customers get to manage their orders giving them more control on the amounts they’ll be required to pay at the end.

Why build a shopping cart with Qwik and Turso?

In the modern accelerated world of short attention spans, users expect to be able to complete tasks fast, regardless of the quality of their internet or where they are located in the world.

We can use Qwik to to render the web experience as close to user’s expectations because the framework makes it easy to provide users with an instant-on web experience regardless of the size of the app or type of device they are accessing it through. We employ Turso to handle the data persistence side of the puzzle, since it is a database at the edge, meaning it will be able to provide data from the closest possible location to the user, hence reducing latency which translates to a faster browsing experience. Turso does all this without neglecting the data security obligations it has towards its user data.

Research shows that slow websites:

Building the shopping cart

As established, we’ll employ Qwik on the front-end side of the equation and use Turso to persist the shopping data. We won’t address user authentication on this post and instead assume that the user is already signed in.

In this post I’ll break down the implementation of a shopping cart into several parts:

Product listing
The cart
Checkout
Order placement

Pre-requisites: You need the latest LTS version of node.js and the Turso CLI installed in your system to proceed.

We will not cover the creation of a Qwik project and Turso database as we have excellent resources to follow on that topic. There is a GitHub repositorythat has the full source code of the shopping cart being created here, you can use its README to assist you with setting up the database, its schema, and indexes.

Follow the data seeding instructions to add some demo data to the database if you’ll opt to go straight to the repo and skip this post.

As in most apps, we’ll first need a set of utility functions that we will be referencing in the steps that follow. We’ll place these functions under the /src/utils/ directory

The first utility function is the Turso client that exports a libSQL client instance.

// /src/utils/turso-db.ts

import { createClient } from "@libsql/client";
const config = {
  url: import.meta.env.VITE_TURSO_DATABASE_URL,
  authToken: import.meta.env.VITE_TURSO_DATABASE_TOKEN
}
export const client = createClient(config);

And lastly the types that we are going to use within the app, which can also be found in this file.

Product listing

For product listings we make database requests that query data by category and display it on the listing pages.

For example, in the category page where we list products based on shared categories whose ids are passed as part of the page URL, we have the following Turso query.

client.execute(
  sql: "select * from products where category_id = ?",
  args: [categoryId]
);

We add the above query inside Qwik’s routeLoader$ where we are able to access the route parameters and collect the category id categoryId which we then use to filter the data being queried from the database as can be viewed in the code block above.

When you check this source code file on the repository you’ll see that we have useCategoryLoader as the routeLoader$ within this page. We then get the data returned by this loader inside the Qwik page component as a reactive Signalas follows.

export default component$(() => {
  const pageData = useCategoryLoader();
  // other code
}

Afterwards, we can list the items on the template like this.

return (
  <!-- -->
  <ul class="mt-4 grid gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
    {
      pageData.value.products.length > 0
      ? pageData.value.products.map((product: Product) => (<ProductCard product={product} key={product.id} />))
      : <div class="p-8">No items</div>
    }
  </ul>
  <!-- -->
)

The cart

For the most important feature of the shopping cart, we are aiming for two things

Making sure that our cart data is persisted on the database so that users can easily resume where they left off their shopping sessions on any device.
Enabling the users to be able to preview the cart from anywhere within the app in the form of a “mini cart”.

We handle persisting the data to Turso by adding a function that inserts the data whenever a user clicks on the “Add to cart” button.

// /src/components/product-card/ProductCard.tsx

const addToCart = $(async () => {
  try {
    await client.execute({
      sql: "insert into cart_items(product_id, user_id) values(?, ?)",
      args: [props.product.id, authenticatedUser.value.id]
    });
    const cartItem = await client.execute({
      sql: "select * from cart_items where product_id = ? and user_id = ?",
      args: [props.product.id, authenticatedUser.value.id]
    });

    appState.cart.items.push(cartDataAdapter(cartItem.rows)[0])
  } catch (error) {
    // TODO: Catch error and notify user
  }
})

return (
 <button
   class="block w-full rounded bg-yellow-400 p-4 text-sm font-medium transition hover:scale-105"
   onClick$={addToCart}
 >
   Add to Cart
 </button>
)

To enable users to preview the cart details wherever they are on the site, add a cart component (mini cart) under /src/components making it occupy a fixed position on the page, and add ability to toggle its visibility.

Here is how we’ve done this using Qwik: checking this file you’ll notice that we are toggling the app context’s cart.show value stored in the appState and also setting it to false whenever the Esc key is pressed.

const closeCart = $(() => {
  appState.cart.show = !appState.cart.show;
});

// hide cart when esc key is pressed
useOn("keydown", $((event: unknown) => {
  if((event as KeyboardEvent).key === "Escape") {
    appState.cart.show = false;
  }
}))

To list the cart items within this mini cart, fetch the items stored under the currently logged in user from the cart_items table as follows.

// /src/components/cart/Cart.tsx

useTask$(async () => {
  try {
    const storedCartItems = await client.execute({
      sql: "select cart_items.count, cart_items.id as cart_item_id, products.* from cart_items left join products on products.id = cart_items.product_id where user_id = ?",
      args: [authenticatedUser.value.id]
    });

    appState.cart.items = cartDataAdapter(storedCartItems.rows);
  } catch (error) {
    // TODO: Catch error and notify user
  }
})

The cartDataAdapter function helps us convert the collected data into the app’s CartItem type.

We are using Qwik’s useTask$ hook in the above code block since it’s called at least once when the component is created. This is beneficial for our app as the request is made in the server layer when the page loads, hence reducing the number of requests made on the client side. If the app is not making a new page load the request will still be made on the client layer and we’ll have the mini cart populated with data anyway.

For the cart page, the data fetch requests made are more or less the same as within the mini cart with the difference being that they are made inside a routeLoader$ .

One good practice inside the cart page is the placement of recommendations right at the bottom of the cart on display. This enables users to either see alternatives or add items that they’d like to have together with the items within the cart. Use the data collected over time within your shopping cart to come up with an algorithm that better suits the items to be placed here.

In our shopping cart we have a Recommendations component placed inside the cart page that displays four items that exclude any of the ones existing in the cart, picked randomly from the products table.

// /src/components/recommendations/Recommendations.tsx

const placeholders = appState.cart.items.map(() => {
  return "?"
}).join(",")
const values = appState.cart.items.map(item => {
  return item.product.id;
})

try {
  const response = await client.execute({
    sql: `select * from products where id not in (${placeholders}) order by random() limit 4`,
    args: values
  });

  recommendedProducts.value = response.rows as unknown as Product[];
} catch (error) {
  // TODO: Catch error and notify user
}

Checkout

17% of consumers abandon their carts due to long or complicated checkout processes. To avoid making your users part of this statistic, go for the simplified one-page checkout process.

In the checkout code of the shopping cart, you can observe that we’ve opted for the simplified one page checkout where the user is presented with all fill in forms from his contact information, shipping details, to payment cards.

Within the checkout, just like in the cart we are fetching the cart data persisted on Turso and listing it as the order summary of the items that the user is buying.

Order placement

After funnelling users through, you eventually want them to place orders and make your efforts in creating this whole thing worthwhile.

In this section I’m not going to give or suggest a payment option, choose your own payment service and plug it in. I will only explain and try to demonstrate what happens when a user clicks the “Pay Now” button we saw in the previous step.

After verifying and making sure the payment went through, submit the items currently in the user’s cart_items table as a new order, attaching this order with the customer contact information and address just as required by the orders table.

await client.execute({
  sql: "insert into orders(user_id, customer_name, amount, shipping_fees, discount_amt, final_amount, shipping_address, paid) values(?, ?, ?, ?, ?, ?, ?, ?)",
  args: [authenticatedUser.id, `${authenticatedUser.first_name} ${authenticatedUser.last_name}`, amount, calculatedShippingFees, discountAmount, finalAmount, `${shippingAddress.zipCode} ${shippingAddress.country}`, true]
});

Then clear the items from the cart_items table after having transferred them to the order_items table.

// /src/routes/checkout/index.tsx

const transaction = await client.transaction();
const newOrder = await transaction.execute({
  sql: "insert into orders(user_id, customer_name, amount, shipping_fees, discount_amt, final_amount, shipping_address, paid) values(?, ?, ?, ?, ?, ?, ?, ?)",
  args: [authenticatedUser.id, `${authenticatedUser.first_name} ${authenticatedUser.last_name}`, amount, calculatedShippingFees, discountAmount, finalAmount, `${shippingAddress.zipCode} ${shippingAddress.country}`, true]
});

for(const item of appState.cart.items){
  transaction.execute({
    sql: "insert into order_items(order_id, product_id, count) values(?, ?, ?);",
    args: [newOrder.lastInsertRowid as unknown as number, item.product.id, item.count]
  });
  transaction.execute({ 
    sql: "delete from cart_items where id = ?;",
    args: [item.id]
  }); 
}
await transaction.commit();

Inside the project this is done in Qwik’s server$ function as seen here.

And that’s how you create a shopping cart for your business using this Quick stack.

More features can be added to broaden the user experience but it ought to be done with functional relevance. Customer satisfaction is mainly what we are looking for when trying to get them to end up making purchases in e-commerce websites.

An example of a feature that could be added include user reviews and ratings which tend to foster more confidence in users since they can read about the experiences of others who’ve used the website before.

For more information on the stack used here, you can visit the following resources.

Deploying a web app built with Qwik and Turso on Netlify

James Sinkala — Wed, 05 Jul 2023 14:46:13 +0000

Unless we are tweaking around or playing with new tech for the sake of learning, most times we are working on products that we ultimately would like to share with the rest of the world. In such scenarios, services such as Netlify are among the household names when it comes to hosting projects for the web.

Netlify lets developers skip DevOps and set up projects globally in a production-ready, rollback-supporting, and scalable environment.

In this post, we are going to learn how to deploy a Qwik application that stores its data in Turso.

For an introduction to the stack being used in creating the project in this post, Qwik and Turso, you can refer to this blog post, or the Qwik docs and an earlier blog post I wrote documenting my early Turso impressions.

Anatomy of the application

The app we are going to deploy on this post is a social link listing site (FindMeOn), we are specifically going to deploy this app on Netlify’s edge functions.

The social links listing app is made of two pages. The first contains a form that enables users to submit their user details, including the social media links they like to list as part of their profiles to the Turso database.

While the second page lists a person’s social links, which within the source code we are fetching the data from Turso, and listing it.

Setting up Turso

The Turso setup for this app consists of a database and two tables, users and lists, the earlier containing user details such as a username, a name, and email, and the latter the social links URLs such as YouTube, Twitter, Linkedin, etc. Visit the project’s README to get directions on how to set up Turso for this project.

The source code for this project can be found on this GitHub repo.

Deploying the app on Netlify

Netlify’s Edge Functions connect the Netlify platform and workflow with an open runtime standard at the network edge, which enables you to build fast, personalized web experiences with an ecosystem of development tools that has support for both TypeScript and JavaScript, since Netlify’s edge runtime runs on deno.

With Netlify’s edge functions, you can modify network requests to localize content, serve relevant ads, authenticate visitors, A/B test content, etc.

Edge Functions also support a new generation of edge-first web frameworks that allow your entire app to run at the edge, dramatically increasing performance. This is true in the case of Qwik: the framework we’ve built the project being deployed on this post with.

So, Qwik bundles its production JavaScript files and makes them available on the edge, but to use the edge-specific context for localization, geolocation, content rewrite and more, we need to create and use custom-created edge functions, just as we’ll see in a short while.

Before proceeding with the next steps, make sure you have signed up for a Netlify account.

Authenticate to Netlify at the command-line level for global installation by running netlify login.

Creating Netlify Edge functions

To create an edge function in Netlify, first, create a JavaScript/TypeScript file under the netlify/edge-functions directory within a project, exporting the function as a default.

Then, create a route path at which the functions should be accessed. There are two ways to go about creating a function’s path, the first being, exporting a config object containing the path to the function as its property.

export const config = { path: "/test" };

And, the second, involves adding the path to the function on the edge_functions section of Netlify’s configuration file netlify.toml on the root of the project. For a function file with the name test.js or test.ts, this is how you would set its path on the configuration file.

[[edge_functions]]
  path = "/test"
  function = "test"

Inside this project, we are fetching a localized greeting using a Netlify Edge function. To see the source code, open the netlify/edge-functions/local-greeting.ts file on the project’s repo.

In the source code, you can see that we are returning a localized greeting which is determined by checking the geolocation data of the source of the request. This piece of information is obtained by checking the Netlify-specific Context object.

Deploying the app

There are two ways to deploy the app on Netlify, the first is by using the netlify-cli, and the second is through the Netlify dashboard. Here is a list of steps to follow for the latter.

First, stage the project and push it to GitHub.
Open your Netlify dashboard and add a new site.

On the next page, you’ll get to choose the Git client where your project is stored, in this case, GitHub. Choose it to proceed.

Next, search and pick your project’s repository.

Set the site settings for your project, including selecting the production branch, build command, publish and base directory. For most frameworks, Netlify auto-detects and sets up default configuration.

One of the most important settings in this step is the setting up of the project’s environment variables. For this project, we need to set up the VITE_TURSO_DB_URL and VITE_TURSO_DB_AUTH_TOKEN environment variables which are the two credentials enabling us to communicate with the Turso database within this site.

Finally, deploy the site.

Click here to see the deployed version of this project on Netlify.

Preview of FindMeOn as deployed on Netlify.
So, this is how we can deploy Qwik apps on Netlify, while using Netlify Edge functions to utilize the edge-specific context.

To learn more about Netlify’s edge functions, visit the official documentation.

For a thorough guide on integrating Turso apps with Netlify, visit Turso’s Netlify integration guide.

Creating a newsletter manager with Turso and Qwik

James Sinkala — Fri, 23 Jun 2023 19:58:08 +0000

A newsletter is an email marketing strategy tool used by individuals, publishers, organisations, businesses to share valuable information and engaging content with their customers, helping in promoting sales and driving traffic to their websites.

In this post I’m going to demonstrate how to create a newsletter using Turso, the edge database based on libSQL - the open-source and open-contribution fork of SQLite, and Qwik, the resumable, instant-on applications framework being built by the folks at builder.io.

Before getting to the building part, I’d like to share a couple of reasons as to why I’m working on this and using the selected technology.

Newsletter platforms are either unreliable or expensive, here’s why I rolled my own

My go-to option for my own newsletters had been Revue, but Twitter recently shut that down, and others like Ghost and ConvertKit are quite expensive for my liking, so I did some research into building my own so you don’t have to.

I have been following Qwik, a resumable, instant-on applications framework, and I love the philosophy behind it, so it was a no brainer to build with. I paired it with Turso, a DBaaS (Database-as-a-service) that has the best DX (Developer Experience) I’ve come across — which is one of the reasons I ended up joining the company, full disclosure — for the speed and low latency it can provide alongside Qwik.

Creating the newsletter manager with Turso and Qwik

The newsletter manager we are creating has three pages.

The first page is one that subscribers interact with when subscribing, which includes a brief introduction to what the newsletter is all about, and a form.

The second, a page accessible to the newsletter’s editor which enables them to view the subscribers emails, blogs they subscribed to(if multiple), and the subscription dates.

The third page is the unsubscribing page. Like any good newsletter, you’d want to give your subscribers both the option to opt-into and opt-out of it.

Ideally, the second page would involve authentication of some sort as it should warrant limited access, but we won’t be covering authentication in this post.

The source code to the project we are working on in this post is also available in this GitHub repository.

Prerequisites:

Before proceeding, make sure that you have the latest LTS version of Node.js to build Qwik projects and use node modules.
Sign up for a Turso account to use the Turso CLI to create databases for your projects.

Setting up the Turso database

Instructions on the installation of Turso, database creation, and getting the Turso database URL can be found on the project’s initialization instructions on the GitHub repository.

You’ll need the Turso database URL obtained after creating a database as that is needed inside our application.

The Qwik app

As discussed, and as you'll notice by observing the source code, the project is built using the Qwik framework, and we are using the libSQL's client for TypeScript (@libsql/client to perform queries on our database. With this, we can work with local SQLite file databases seamlessly just like using our Turso databases on the edge.

Something that we are going to be seeing repeatedly in Qwik code is the $ symbol. Let it not confuse you, Qwik uses it to signify the extraction of code to both the developer and Qwik optimizer. Qwik splits up the application into many smaller pieces dubbed "symbols" using the Qwik Optimizer. More on this can be read in the Qwik docs.

Let's cover the most interesting bits of the newsletter manager.

The newsletter home page

Inside the home page, we are updating the loading state and calling the subscribeToNewsletter() function when the form is submitted <form onSubmit$>.

useSignal() and useStore() are two Qwik hooks you’ll find throughout the pages used to declare reactive state. useSignal() takes an initial value and returns a reactive signal consisting of an object with a single .value property, while the useStore() hook takes an object as its initial value and returns a reactive object.

The server function in Qwik — server$ lets us work in the server layer of the application right next to our client code. Here is more information on it, and here is a demonstration.

subscribeToNewsletter() inside the home page is a server function that submits the subscription information to the Turso database and updates us on the subscription state.

import { createClient } from "@libsql/client";

export const subscribeToNewsletter = server$(
  async (email: string, newsletter: string) => {
    if (!email || !newsletter) {
      return {
        success: false,
        message: "Email cannot be empty!",
      };
    }

    const db = createClient({
      url: import.meta.env.VITE_DB_URL,
    });

    await db.execute("insert into newsletters(email, website) values(?, ?)", [
      email,
      newsletter,
    ]);

    const response = await db.execute(
      "select * from newsletters where email = ? and website = ?",
      [email, newsletterBlog]
    );

    const subscriber = responseDataAdapter(response);

    return subscriber[0]
      ? {
          success: true,
          message: "You've been subscribed!",
        }
      : {
          success: false,
          message: "Sorry something isn't right, please retry!",
        };
  }
);

export default component$(() => {
  const email = useSignal("");
  const loading = useSignal(false);
  const emailRegex = /\b[\w.-]+@[\w.-]+\.\w{2,4}\b/gi;
  const notification = useStore({
    message: "",
    status: "",
  });

  return (
      <form
        preventdefault:submit onSubmit$={async () => {
          if (!emailRegex.test(email.value)) {
            alert("Email not valid!");
            return;
          }
          loading.value = true;
          const response = await subscribeToNewsletter(
            email.value,
            newsletterBlog
          );
          loading.value = false;
          notification.message = response.message;
          notification.status = response.success ? "success" : "error";
        }}
      >
        <input
          onInput$={(e) => {
            email.value = (e.target as HTMLInputElement).value
          }}
          name="email"
          type="email"
        />
        <button
          type="submit"
        >Subscribe</button>
      </form>
  );
});

Qwik also supports SEO (Search Engine Optimisation). To set it up on pages, we export a head object of the DocumentHead type with HTML header metadata. We can see this inside each of the three pages, the home, admin, and unsubscription pages.

Here’s a preview of the home page.

The newsletter admin page

In the component UI of the newsletter admin page, we are using Qwik’s Resource component which renders its children when the passed resource is resolved, and renders a fallback when it is pending or rejected.

In Qwik, resources are created using the useResource$ method. We can see a demonstration of a resource by looking at the subscribersResource needed by the <Resource ... /> component referenced above.

const subscriberRows = (subscribers: NewsletterSubscriber[]) => {
  return subscribers?.length < 1 ? (
    <tr>
      <td
        colSpan={4}
      >
        No subscribers found
      </td>
    </tr>
  ) : (
    subscribers?.map((sub: NewsletterSubscriber, index: number) => {
      return (
        <tr key={sub.id}>
          <td>{index + 1}</td>
          <td>{sub.email}</td>
          <td>
            {sub.website}
          </td>
          <td>
            {formatDate(sub.created_at)}
          </td>
        </tr>
      );
    })
  );
};

export default component$(() => {

  const subscribersResource = useResource$<ResourceResponse>(async () => {
    const response = await db.execute('select * from newsletters');
    const subscribers = response?.success ? responseDataAdapter(response) : [];

    return {
      message: "Fetched subscribers",
      data: subscribers,
    };
  });

  return(
    <div>
      <h1>Newsletter Admin</h1>

      <Resource
        value={subscribersResource}
        onRejected={() => <Noty message="Failed to fetch subscribers" type="error" />}
        onPending={() => <LoadingAnimation/>}
        onResolved={(res: ResourceResponse) => <table>
          <thead>
          <tr>
            <th>No.</th>
            <th>Email</th>
            <th>Website</th>
            <th>Joined</th>
          </tr>
          </thead>
          <tbody>
            {subscriberRows(res.data)}
          </tbody>
        </table>
        }
      ></Resource>
    </div>
  );
});

After adding some subscribers, we should see the table populated with their information when visiting this page.

The newsletter unsubscription page

Normally unsubscription links should be accessible from within the newsletter emails. To unsubscribe users, we need to pass parameters to the unsubscription route.

Qwik’s file-based routing is similar to other frameworks, in that we pass route parameters declaring them as directory names inside square brackets.

To pass the domain and email parameters, we’ve set up the directory structure for the unsubscription page as follows.

└── routes
    ├── unsubscribe
    │   └── [email]
    │       └── [domain]
    │           └── index.tsx

We then use Qwik’s useLocation() function to retrieve a RouteLocation object for the active location from which we acquire the email and domain parameters. We use these two parameters to delete the user’s data from the database, to unsubscribe them from the newsletter inside another server function.

The whole unsubscription process is automated by making sure that unsubscribeFromNewsletter(), which is also a Qwik server$ function, is triggered when the page component is rendered on the browser. We do this by calling this function inside the useBrowserVisibleTask() hook.

import { createClient } from "@libsql/client";

export default component$(() => {
  const location = useLocation();
  const email = useSignal(location.params.email);
  const domain = useSignal(location.params.domain);
  const loading = useSignal(false);
  const notification = useStore({
    message: "",
    status: "",
  });

  const unsubscribeFromNewsletter = server$(async () => {
    const db = createClient({
      url: import.meta.env.VITE_DB_URL,
    });
    const deleteRecord = await db.execute(
      "delete from newsletters where email = ? and website like ?",
      [email.value, domain.value]
    );

    if (!deleteRecord.success) {
      return {
        success: false,
        message: "Sorry, something isn't right, please reload the page!",
      };
    }

    return {
      success: true,
      message: "Unsubscribed!",
    };
  });

  useBrowserVisibleTask$(async () => {
    loading.value = true;
    const res = await unsubscribeFromNewsletter();
    notification.message = res.message;
    notification.status = res.success ? "success" : "error";
    loading.value = false;
  });
});

Here is a demonstration of what would happen when unsubscribing users, starting inside the mail view.

That’s it for the newsletter manager. Visit the project’s repo on GitHub for the source code and to learn more about it.

To learn more about Turso click here to visit the documentation, and as for Qwik, you can read the official documentation over here.

Creating A Hot New Food Delivery App with Novu

James Sinkala — Mon, 24 Apr 2023 12:20:01 +0000

TL;DR

In this tutorial, we’ll create a tool to manage a notification system for a food delivery app. To do so, we’ll use the power of the open source notification infrastructure from Novu alongside our custom platform and PostMark.

Join the ConnectNovu Hackathon

Showcase your skills, push the boundaries of innovation, and meet like-minded community members.

ConnectNovu Hackathon is a global event focused on notifications. If you love playing with In-App, SMSs, Push notifications, Emails, and chats, that's the place for you!

Are you ready to build the next big thing? 🚀

JOIN HERE

The Kick-Off

We all love the new era of delivery apps. No calls, complete your order on your phone in minutes, pay a huge delivery fee, and then eagerly wait until our food arrives at our door.

But in this process, those delivery apps keep you in the loop for the entire operation — from order placed to package delivered. But to do so, you’ll need a robust notification system to take care of it.

In this tutorial, we will learn how to create a notification management system for a food delivery app using Novu, a powerful open source notification infrastructure.

If you want to jump to the source code for this tutorial, check it out here.

Jumping Into Business

For this tutorial, we’ll just start with a simple app named Foody. We’ll create the project with Nuxt and Supabase, but you can tag along with any JavaScript framework you’d like. You’ll also need the LTS version of Node.js too.

Typically, there are a set of notifications we’d expect to receive in any e-commerce service, and the food delivery system is no exception. For Foody, we’ll need at least the following types of notifications:

Customer hospitality notifications: Welcoming and thanking users.
Service-specific notifications: - Order placement, delivery status, feedback requests, promotions.
Legal and security updates notifications: Terms and privacy, etc.

Let’s see how Novu can handle some of these notifications in a food delivery service context.

Getting Our Project Started

We’ll need to sign up for a Novu account and start setting up our project.

After that, we must set up at least one delivery provider. That delivery provider will be used to manage all of our notifications within our app. So head over to the Integration Store to see our options.

At the time of writing, Novu supports three notification channels: email, SMS, and an in-app notification center. If you want to create a notification provider other than the provided ones, check out their documentation.

We’ll set up a new provider using Postmark for Foody. Let’s go ahead and do this.

Setting Up PostMark

Starting off, we’ll need a PostMark account too. Once that’s done, we’ll need to verify a sender and create a new Server API Token if one doesn’t already exist.

Back at the Novu Integration Store page, click connect on Postmark, fill in the Server API token as the API Key on the form presented, and set from email to the sender verified on Postmark. Lastly, provide a sender name, toggle the provider to active, and click the connect button.

Creating Notifications on Novu

To create a new notification on Novu, click the Notifications page and the New button on the top-right side. Fill in the notification settings for the new template by providing the Notification Name, Notification Description, and Notification Group, which is set to General by default.

Send A Welcome Notification

For Foody, we’ll set up a customer welcoming email to demonstrate how to set up notifications in Novu. Fill in the fields in the previous figure, setting the Notification Name to welcome-new-user and the Notification Description to Notification for welcoming newly registered users.

Proceed to the new notification's Workflow Editor tab to add steps. In our case, we want to send an email notification welcoming the customer and then receive an in-app admin dashboard notification for them. So, on this page, drag the email step to the canvas, followed by the in-app step.

Select the email step currently inside the canvas and edit the template. You can use the visual template editor or write custom markup for email channels. We’ll be using the template editor:

The Steps Variables section on the right side of the editor lists the variables we’ve used inside the email template in the handlebars - {{}}. These variables will be populated by the submitted email payload sent through a Novu trigger. You can preview and test the created email notification for troubleshooting on completion.

Back in the workflow editor, select the In-App step and edit its template too:

Call this trigger after the user account validation to trigger this notification inside Foody.

Integrating Novu into Foody

If you followed the Nuxt app provided for this tutorial, the following logic has been set up inside a server API endpoint file - /server/api/register-notifications-subscriber.js. This notification serves two purposes, the first being the registration of the app user as a Novu notifications subscriber and the second being the sending of the welcoming email.

// dependency imports

export default defineEventHandler(async (event) => {
    // variable declarations

    // Send welcome notification to new user
    const [firstName, lastName] = user.user_metadata.full_name.split(" ");
      await novu.trigger('welcome-new-user', {
          to: {
            subscriberId: user.id,
            email: user.user_metadata.email,
            firstName,
            lastName,
            phone: user.user_metadata.phone,
          },
          payload: {
            firstName
          },
        });

    // other code
})

Despite not using it in the email template, we are providing as much subscriber data as possible to the trigger in the above code. Why? Because when the trigger is called, Novu upserts the data to a new subscriber, and if none exists, it creates a new one.

To explicitly create a new subscriber, use this:

    await novu.subscribers.identify(user.id, {
      email,
      firstName,
      lastName,
      phone: user.user_metadata.phone,
    });

After having registered some users, we should see the following when visiting the Activity Feed section of the Novu dashboard:

The activity feed monitors all outgoing messages associated with a Novu project. It can monitor activity and discover potential issues with providers or channels.

Sending Order-Specific Notifications with Novu

Now that we’ve seen how it all works for sending welcome emails to our Foody users, let’s do it again for our actual orders!

Sending Order Confirmations

Like any other food delivery app, we want to keep our customers in the loop. So next, we’ll need to set up a notification that confirms their order once it’s been placed.

Create a new notification following the previous steps, setting the Notification Name to "order-confirmation" and the Notification Descriptionto "Notifying users on order placement".

For this notification, we would like to send a list of dishes the user purchased. Hence the suitable way to write the email template would be using the following custom markup:

<div>
 Hello {{subscriber.firstName}},
</div>

<div style="padding: 4px">
 You successfully placed order number #{{orderNumber}}.
</div>

<ul style="padding: 4px">
 {{#each dishes }}
  <li>{{count}} x {{name}} </li>
 {{/each}}
</ul>

<div style="padding: 4px">
 Delivery Fees: {{deliveryFee}}$
</div>

<div style="padding: 4px; font-weight: 800">
 Total: {{totalFee}}$
</div>

<div style="padding: 4px">
 Please notify us if any dish is out of order.
</div>

We can see two new things in the above template that differentiate it from the email templates we created earlier.

First, we have the subscriber.firstName variable. Novu manages an app’s users in a specific subscribers data model, which allows the API to manage different aspects of the notification flow while providing an easy interface for triggering notifications. The subscriber.firstName variable comes from the user data point of the subscriber object allowing its placement inside the notification template. Other data we can obtain in the user data point include the lastName and avatar.

The second part that is different from the previous templates is the iteration through the dishes array. This is made possible by using the handlebars #each helper. We also have access to the conditional #if handlebars helper, which we’ll demonstrate its usage in coming sections of notifications.

To send the order-confirmation notifications to our Foody customers using the created template, add the following trigger:

// imports and global functions

export default defineEventHandler(async (event) => {
    // variable declarations

    // order creation logic providing us with orderDetails variable

      await novu.trigger('order-confirmation', {
          to: {
            subscriberId: user.id,
            email: user.user_metadata.email
          },
          payload: {
            dishes: order.dishes,
            orderNumber: orderDetails.order_number,
            deliveryFee: order.deliveryFee,
            totalFee: order.totalFee
          },
        });

    // other code
})

Sending Delivery Status Notifications

To keep customers in the loop, we’d like to notify them of changes to the delivery status of the orders they place. Create a new delivery-status notification, and use the following code as its template:

<div>
 Hello {{subscriber.firstName}},
</div>

<div style="padding: 4px">
 You order #{{orderNumber}} has been {{status}}.
</div>

<div style="padding: 4px">
 Click the following link to give us a feedback of your order.

 {{#if delivered}}
  <p>
   <a href="{{feedbackUrl}}" target="_blank" style="padding: 2px">
    Give us feedback
   </a>
  </p>
 {{/if }}
</div>

Delivery status notifications can be “order picked up”, “ order delivered”, and more. When the order has been delivered, with the assistance of the handlebars #if helper, we can also send the user a link to give us feedback on the delivery.

The last single subscriber-based notification we would create for Foody is a feedback appreciation notification. We can use the template editor to make this notification since it’s less complex than the last two.

The following code can be used as the trigger for the notification within the app:

// imports
export default defineEventHandler(async (event) => {
// Declarations and user feedback database-submission logic

      await novu.trigger('feedback-appreciation', {
          to: {
            subscriberId: user.id,
            email: user.email
          },
          payload: {
            firstName
          },
        });

    return {
        message: 'Appreciated user!',
    }
})

Sending Bulk Subscription-based Notifications With Novu Topics

What about when we need to send bulk notifications to a group or all customers? We want to send notifications in bulk for things like promotions, discounts, service updates, and terms and services changes. How do we do this without performing the expensive practice of looping through data?

Novu provides an answer for this pain in the form of Topics. Novu Topics allow us to send bulk notifications to a group of users based on any criteria we define. With Topics, we can send multiple emails to users based on their interests, subscriptions, or any other possible attribute that can be determined.

In our scenario, we may want to send promotional and discount notifications to customers based on the dishes they frequently buy. For instance, if we equate a customer buying a particular dish a certain number of times to mean they like it, we’d add them to a topic that includes customers who like that dish. We might name such a topic as customers:favorite:dish_id.

Adding this sort of functionality to our app will allow us to deliver targeted ads for some of our user bases instead of relying on a shotgun approach to customer engagement.

Creating a Novu Topic

Now that we understand what topics are in Novu let’s learn how to create one.

We will create a topic for Foody that sends promotional notifications to customers based on purchasing behavior, just like we discussed earlier. But before assigning subscribers to a topic, we need to create the topic first.

In our food delivery service scenario, a topic must be created whenever a dish is added to the app’s database. The following piece of topic-creating code would be ideally placed just after the logic that submits a new dish to the database:

// Dish data submission logic

const result = await novu.topics.create({
   key: "customers:favorite:" + newDishData.id,
   name: "Customers that like " + newDishData.name
});

Remember, the Novu topic key should be unique and can’t be changed once created.

Adding New Subscribers And Sending Notifications

To add a new subscriber to a topic, we’ll need to use the addSubscriber() method:

// Order placement logic

// When customer fulfils criteria to be added to topic involving dish[0]
const result = await novu.topics.addSubscribers(
    'customer:favorites:' + order.dishes[0].id,
    {
        subscribers: [user.id]
    })

Inside the app, this should be called just after the order placement code. Users will be added to a topic if they fulfill the criteria.

Having created a topic and added some subscribers, the next step would be sending notifications to its subscribers. First, create a notification for the topic in question, such as dish-based-promotional-notification. Don’t forget to add a template for this too!

Finally, create a trigger that sends the notifications. Novu’s topic notifications trigger is the same as the one used to send notifications to single subscribers. The difference is that, on the to field, instead of placing the single subscriber's identity, we pass an array of topics whose subscribers we’d want to receive the notifications.

Here is a trigger example for the created notification:

import { Novu } from '@novu/node';
import { TriggerRecipientsTypeEnum } from '@novu/shared'

export default defineEventHandler(async (event) => {
    // initiate Novu

    const result = await novu.trigger('dish-based-promotional-notification',{
        to: [{ type: TriggerRecipientsTypeEnum.TOPIC, topicKey }],
        payload: {
            promotionTitle,
            promotionDetails
        }
    });
})

Customizing Notification Options

Not all customers would like to receive every kind of notification from the food delivery service. Therefore, we should allow them to opt out of some topics. What we’ll be doing is merely subscriber management within specific topics.

To demonstrate this, we’ll go to the dish-based-promotional-notification notification template that we created earlier and add an unsubscribe link at the bottom. Since it’s not feasible to add a link in the template editor, convert the whole template to custom code with the following markup:

<div>
 Hello {{subscriber.firstName}},
</div>

<div style="padding: 4px">
 We have an offer you wouldn't want to miss.
</div>

<div style="padding: 4px">
 {{promotionDetails}}
</div>

<div style="padding: 4px">
 <a href="{{optOutLink}}?userId={{subscriber.subscriberId}}&topicKey={{topicKey}}" target="_blank">Click here</a> to unsubcribe from these emails.
</div>

We need their subscriber ID and the topic key to remove a subscriber from a topic, as demonstrated in the above markup. Since we never passed the topic key in the trigger involving this notification, we need to make the following changes to it:

const result = await novu.trigger('dish-based-promotional-notification',{
    to: [{ type: TriggerRecipientsTypeEnum.TOPIC, topicKey }],
    payload: {
        promotionTitle,
        promotionDetails,
        topicKey
    }
});

Now, we can proceed to create a topic-opting-out trigger for users. As explained, we are simply removing the subscriber from the topic. To do that, we need to call the removeSubscribers() method as follows.

const result = await novu.topics.removeSubscribers(topicKey, {
    subscribers: [userId]
});

The Wrap-Up

It turns out a lot is going on behind the scenes of these food delivery apps! While we don’t have a fully functioning Foody app, we do have an excellent notification infrastructure in place, thanks to Novu! We used Supabase to handle our user authentication, but the most significant part was adding in some notification functionality.

If you liked what you saw here, let us know in the comments below! It’s been a pleasure, and I hope you take Foody to new heights!

P.S ConnectNovu Hackathon is live, everybody is invited to register, and there are some cool prizes too, check it here.

Understanding Vue.js Single-File Components (SFCs)

James Sinkala — Wed, 29 Mar 2023 23:39:10 +0000

If you have been reading these posts in chronological order, you know that up to this point, we’ve been creating and running our Vue.js apps inside HTML pages as part of page scripts.
Vue.js gives us the freedom to create apps in this way, depending on the extent of features we are expecting our Vue.js apps to have within the apps we are building.

We have seen that, Vue.js can serve the purpose of adding atomic features within other apps/HTML pages, for example, it can be used in the search bar section of a website only, sending search requests, and displaying results per the inserted queries.

But, there are cases where we need to build fully-fledged Vue.js apps with whole sets of features such as routing, state management, etc. Such apps normally involve writing a lot of Vue.js code, and, as it's expected in such instances, we get large files containing lots of code which normally leads to all sorts of code maintenance issues down the line.

To avoid these imminent time and resource-consuming troubles, we normally break down code into smaller manageable and dependent chunks as we’ve seen with the Vue.js components.

But, the scenario we’re referring to here goes beyond breaking down Vue.js apps into smaller components, but further into independent files called Vue.js Single-File Components (SFCs) that are by themselves fully-fledged and pluggable Vue.js apps.

Here are some of the benefits of using Vue.js SFC files:

The improvement to developer experience, by encouraging the use of build tools that do the heavy lifting for us aiding in the automation of tasks such as code prettifying, linting, and minification for production to facilitate the making of light deployment bundles, best practices and so forth.
We can easily re-use SFCs within other apps where we would want to re-implement related features and avoid re-writing code.
We can bundle components and create sharable plugins, facilitating the sharing of code with other developers. This is a very beneficial practice in software development since when fixes are made or features are added they are easily distributed to all apps these plugins are used in.
The grouping of all code (logic, template, and styling) related to a single function within a single file simplifies the management of our apps and their independent features.

The Vue.js SFC files have a unique .vue file extension which is supported by all major IDEs, text editors, and several plugins that help highlight the Vue.js code and apply code intellisense to it.

Working with Vue.js Single-File Components(SFCs)

To see the syntax and work with Vue.js SFCs, you’ll first need to scaffold a Vue.js project that’s managed with a build tool called Vite.

We’ll work with Vite but won’t place much focus on it in this post, more of its specifics will be learned in the future, for now, all we need is to understand that it’s a build tool for front-end JavaScript frameworks.

Before proceeding make sure that you have the latest LTS version of node.js installed into your system.

Run the following command on the terminal to create a new Vue.js project directory.

mkdir vue-sfc-app

When this command terminates, well should have a new directory named vue-sfc-app. Switch the active terminal location into it by running cd vue-sfc-app.

Inside the project directory, run npm init -y to make this directory the root of a new JavaScript project. This command adds a package.json file, which simply is a project’s metadata file that keeps a manifest of our dependencies, scripts, etc. To read more about this file, you can visit its docs.

So far, this will be the project’s directory layout:

.
├── package.json

Here’s what’s contained in the package.json file so far.

{
  “name”: “vue-sfc-app”,
  “version”: “1.0.0”,
  “description”: “”,
  “main”: “index.js”,
  “scripts”: {
    “test”: “echo \”Error: no test specified\” && exit 1”
  },
  “keywords”: [],
  “author”: “”,
  “license”: “ISC”
}

Add a ”type”: “module” property to this file and keep in mind of what is contained in it.

Run the following commands on the terminal.

npm install vue

npm install -D vite @vitejs/plugin-vue

The first command installs the Vue.js npm package (providing us with the Vue.js library code). The second command installs Vite and its plugin for Vue.js. The two latter dependencies will handle our local development environment with tasks such as compiling the SFC files and serving the app locally so that we can only focus on building our app.

After these two files have been installed, you should notice a new directory: node_modules that has been added to your project. This is where the dependencies' source code is stored, we usually don’t make modifications to anything within it.

When you go back to the package.json file, you will notice some changes, two new sections dependencies and devDependencies with the respective dependencies and their installed versions will have been added.

  ...
  “devDependencies”: {
    “@vitejs/plugin-vue”: “^[SEMANTIC-VERSION]”,
    “vite”: “^[SEMANTIC-VERSION]”
  },
  “dependencies”: {
    “vue”: “^[SEMANTIC-VERSION]”
  }
  ...

Add three files to our project - index.html, index.js, and vite.config.js. Place the following code within these files respectively.

<!-- index.html -->
<html>
    <head>
        <title>Vue SFC App</title>
    </head>
    <body>
        <div id=“app”></div>
        <script type=“module” src=“/index.js”></script>
    </body>
</html>

// index.js
import { createApp } from “vue”;
import App from “./App.vue”

const app = createApp(App).mount(“#app”)

// vite.config.js
import { defineConfig } from “vite”;
import vue from “@vitejs/plugin-vue”;

export default defineConfig({
    plugins: [vue()]
});

In the index.js file, we have initiated the Vue.js app in a familiar format, passing a Vue.js SFC file - App.vue inside the createApp() function.

In the index.html file, we have normal HTML markup out-sourcing the JavaScript code from the index.js file.

The vite.config.js file is a special file in projects managed with Vite where the configuration of the tool can be done. What we’ve done in this file is pass the plugin file so that Vite knows what to do when it encounters Vue.js code and files within the project.

We need to add a script inside the package.json to fire up the local server using commands provided by Vite and view what our project looks like.

Inside the scripts section of the package.json file, add a new dev script as follows.

  “scripts”: {
    “test”: “echo \”Error: no test specified\” && exit 1”,
    “dev”: “vite”
  },

Now, run npm run dev --port 3000 on the terminal. This should launch a local server on the 3000 port if it’s not occupied - localhost:3000. Try visiting it on the browser.

If you see the following error, then everything went to plan.

In this error, Vite is simply telling us that it failed to find the App.vue SFC file, which is true since we never created it.

Go ahead and create it. Adding the following code inside.

<template>
    <div>
        He{{ 1 + ‘1’ }}o World!
    </div>
</template>

Vite will handle hot-reloading for our website, and we should see “He11o World!” on our browser.

Anatomy of a Vue.js SFC file

Vue.js SFCs are just HTML files without the <head> section and with a <template> section replacing the familiar HTML <body>.
In general, they are made up of 3 sections, a <template> where the UI markup would be placed (Like in the example above), the component’s JavaScript logic placed between the <script> tags, and a <style> section where the component's styles would be placed.

We have seen something close to this syntax when learning about Vue.js components because in context, this is the same thing but within an independent file.

Let’s place the 1 + ‘1’ in a computed variable to see the component’s JavaScript section’s syntax.

<script>
export default {
    computed: {
        doubleL() {
            return 1 + ‘1’;
        }
    }
}
</script>

When the page refreshes, no changes would have been made to the page since we’re still employing the same logic.

Let’s see another example.
Add the following button to the template.

<button @click=“increment()”>Clicks {{ count }}</button>

And, update the <script> section by adding the data and methods options.

    data() {
        return {
            count: 0
        }
    },
    methods: {
        increment(){
            this.count++
        }
    }

We should now see the following on our page.

To add a bit of space between our HTML blocks, we can add some styling to the component inside the <style> section like this.

<style scoped>
div, button{
    padding: 5px;
    margin: 5px
}
button{
    color: red;
    font-weight: 800;
}
</style>

And, this is how the page would look afterward.

The scoped attribute on the <style> tag above instructs Vue.js to apply the styles within this component only and not elsewhere, when not placed, this component's style will be applied to the global context of the app.

The `<script setup>` sugar syntax in Vue.js SFCs

With Vue.js 3 (and v2.7), Vue introduced a new API to the framework - the composition API, which is a set of APIs that allows us to author Vue.js components using imported functions instead of declaring options, a practice we’ve been doing when authoring our Vue.js components up to this moment. The Options API is still available for use as we’ve demonstrated in all our examples.

With the Composition API, options such as data within our components would be replaced by the ref() or reactive() functions, native javaScript functions would be favored in place of the methods and filters options, and computed would be replaced with the onComputed() function. All the hooks would be placed with functions prefixed with on in the camel-case format, for example, the mounted, beforeUpdate, and unmounted hooks would be replaced with onMounted(), onBeforeUpdate(), and onUnmounted() composition functions respectively.

The <script setup> sugar was later introduced to facilitate a more succinct and ergonomic syntax for SFCs.

Let’s see an example by converting our App.vue component above.

import {computed, ref} from “vue”
let count = ref(0)
const doubleL = computed(() => 1 + ‘1’)

function increment(){
    count.value++
}

The ref() function, as demonstrated above, is used to make variables reactive. To test out the reactivity, try replacing the ref(0) with 0 and count.value++ with count++ to see if the count would increment on button clicks.

ref() takes an inner value passed to it and returns a reactive and mutable ref object that has a single property - .value that points to the inner value. This is the reason we are using count.value and not count inside the increment() function to mutate count.
Inside the template, we do not need to use .value as Vue.js automatically handles that.

For our computed variable doubleL we pass a getter function that also returns a reactive ref object, meaning, if we were to access its value within the JavaScript section of our app, we would use .value.

We can refactor doubleL in this instance, to free up resources used by using a constant instead of the computed property, since its value is not mutated or needed as a dependency somewhere else.

Const doubleL = 1 + ‘1’

Some obvious benefits we see in the conversion of the App.vue component to the Composition API are the reduction in the code footprint, and more application of native JavaScript, though, we do lose a bit of structure.
For more on the Composition API, you can read the Vue.js official docs on the topic.

Binding SFC component state to styles

With Vue.js SFCs, we can link CSS values to the reactive component state using the v-bind() CSS function.

Let’s bind count to the margin value within our styles.

div, button{
    padding: 5px;
    margin: v-bind(count + “px”)
}

When clicking the button we should see the following effect.

N.B., To see the source code for the Vue.js SFC project we’ve just created visit this GitHub repository.

Summary

To summarise, we’ve learned the following in this post:

Setting up a Vue.js project using build tools, in this case - Vite.
Creating and working with Vue.js’ Single-File Components (SFCs).
Understood the syntax and functionality within each section of an SFC.
We’ve been introduced to Vue.js composition API and some popular functions we’ll be using while building interfaces with Vue.js 3.
Learned about how to use the <script setup> sugar within Vue.js SFC files.
We’ve also seen how we can bind the component state to CSS values to render creative effects within our UIs.

For more on Vue.js Single-File Components, read the official Vue.js docs.

Early impressions of Turso, the edge database from ChiselStrike

James Sinkala — Mon, 13 Feb 2023 15:03:19 +0000

I got into the private Beta program of the new ChiselStrike product - Turso, an edge-hosted distributed database based on libSQL - the open-source and open-contribution fork of SQLite.
Turso is hosted using Fly.io, meaning you have 26 regions of choice when it comes to deploying it.

We’ll talk about all of these aspects of Turso in a moment.

I wrote about ChiselStrike last year in a feature post with LogRocket, and if you want to know more about the service, I can refer you to that post.

The Turso Beta program is still open to new applicants(at the time of writing), to get into it, just head to chiselstrike.com.

With Turso, ChiselStrike is trying to “Eliminate application bottlenecks by bringing performance and data portability of open-source, lightweight SQL close to your users with low overhead”.

The idea is for builders to be able to use their current hosting services e.g Netlify, Vercel, and Cloudflare when hosting their apps while building their databases on the edge with Turso, meaning, ChiselStrike is moving away from their previous model that involved hosting their customer's backends to hosting their data, on the edge.

Let’s see how to install and use Turso.

Installing Turso

To use Turso, we need to install its CLI. Currently(time of writing), you need to apply to the private Beta program to be authorised to use it. You need to also have a GitHub account as that is the only supported authentication method.

Here’s how to install the Turso CLI.

# On Mac
brew install chiselstrike/tap/turso

# linux script
curl -sSfL https://get.tur.so/install.sh | bash

Next, authenticate into Turso (at this point, you will be prompted to authenticate with GitHub).

turso auth login

Creating a new database

To create a new database in Turso run the db create command as follows.

turso db create todo

This should give us the following output.

The last command created a database called todo which was deployed in London as that was deemed the nearest deployment zone adjacent to where I am.

Turso’s db command is quite powerful, as we’ll see as we proceed.

Choosing the primary database region

When creating a new database without much configuration, as in the case above, Fly.to determines a default(primary) region depending on our location to deploy the database. To see the list of locations where we can have our Turso databases, run the following command.

turso db regions

This command will display a list of supported regions such as the one below.

London, United Kingdom is listed here as the default region, because it was the best edge location determined by Fly.io relative to my location.

In case, Fly.io picked the wrong region, and we wanted to specify one, run the db create command, passing the id of the region we want our primary database in on the --region flag. We get these region ids from the output of the previous command.

turso db create todo --region jnb

Creating database tables

Before creating new tables in Turso you need to first access the SQL shell using the Turso CLI, and afterwards run table-creating SQL scripts.

To switch to the shell and work on out todo database, run the following command.

 turso db shell todo

Now, let’s create a new tasks table with the following columns.

create table tasks (
    id int primary key,
    task varchar(255),
    completed boolean default false,
    created_at datetime default current_timestamp
);

Run select name from sqlite_schema; to see if the newly created table is listed.

Submitting data to a Turso database

There are some language-specific clients suited for data transaction with a Turso database, such as @libsql/client for TypeScript, libsql-client for Python, and libsql-client for Rust(currently works with Cloudflare workers), but for simplicity, we’re going to use curl scripts.
We’ll interact with the database by sending HTTP POST requests containing the JSON-encoded SQL queries that we’d otherwise run on the SQL shell as already demonstrated. By supporting database interaction via the HTTP protocol, Turso guarantees easy access from all types of applications, especially edge functions.

While previously connecting to the SQL shell, the output Connected to todo at [URL], lists the connection URL at which our database can be accessed.
You can also run the db show list command to see the list of databases and their connection URLs.

N.B., At the current early access program, these URLs aren’t secure. You can see that the username and password are being passed within them. So, share the connection URLs with care, since anyone who has them can access and manipulate your database. A proper auth solution will be added soon.

Let’s seed some data to our tasks table using the following curl script.

curl "https://xinnks:KZobXle750129i86@todo-xinnks.turso.io" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
        "statements": [
          {
            "q": "insert into tasks (task) values(\"Go to the gym\")"
          },
          {
            "q": "insert into tasks (task) values(\"Read some memes\")"
          },
          {
            "q" :"insert into tasks (task) values(\"Take the mice for a walk\")"
          },
          {
            "q" :"insert into tasks (task) values(\"Buy some fruits\")"
          },
          {
            "q" :"insert into tasks (task) values(\"Wate the garden\")"
          },
          {
            "q" :"insert into tasks (task) values(\"Go to the cinema\")"
          },
          {
            "q" :"insert into tasks (task) values(\"Plant a tree\")"
          }
        ]
      }'

Back in the SQL shell, running select * from tasks should give us the list of data added to the table.

We can also send an HTTP POST request to fetch the data from the database, just as we were able to seed some.

curl "https://xinnks:KZobXle750129i86@todo-xinnks.turso.io" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
        "statements": [
          {
            "q" :"select * from tasks"
          }
        ]
      }'

Which should return the following data.

[
  {
    "results": {
      "columns": [
        "id",
        "task",
        "completed",
        "created_at"
      ],
      "rows": [
        [
          1,
          "Go to the gym",
          0,
          "2023-02-07 23:15:57"
        ],
        [
          2,
          "Read some memes",
          0,
          "2023-02-07 23:15:57"
        ],
        // ...
      ]
    }
  }
]

If we want to set all tasks with id <= 3 as completed we can send this POST request.

curl "https://xinnks:6UdS7wi952043B1r@todo-xinnks.turso.io" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
        "statements": [
          {
            "q" :"update tasks set completed = 1 where id <= 3"
          }
        ]
      }'

And, to see the results of the previous request, we can send another request with the SQL query select * from tasks where completed = 1 to fetch the modified rows.

[
  {
    "results": {
      "columns": [
        "id",
        "task",
        "completed",
        "created_at"
      ],
      "rows": [
        [
          1,
          "Go to the gym",
          1,
          "2023-02-07 23:15:57"
        ],
        [
          2,
          "Read some memes",
          1,
          "2023-02-07 23:15:57"
        ],
        [
          3,
          "Take the mice for a walk",
          1,
          "2023-02-07 23:15:57"
        ]
      ]
    }
  }
]

As we can observe in these examples, to make requests to the Turso database, we just need to pass an Array of SQL queries - “statements” as the body of our HTTP request. Each concurrent statement needs to have the SQL query as the value of the property “q”.

We can either send one or multiple statements per the needs of our apps. The query response speeds are fast as we’d expect with SQLite, but, all good indexing practices should be applied for fast query speeds, especially when dealing with large datasets.

Replicating a Turso database into other regions

Since databases are hosted on servers, the response times would normally vary depending on, among other factors, the distance between the users making the requests and the location of the servers responding to them.

To enable users to build applications that serve multiple locations with low response times, Turso, as discussed in the introduction, gives us the option to replicate our databases in 26 locations around the world, as supported by Fly.io.

To replicate an existing Turso database into a region, we use the db replicate command. If we decided to replicate the todo database in Madrid, Spain, we’d do the following.

turso db replicate todo mad

To verify that the data we had in the primary version of the todo database has been replicated to our new replica, open the shell of the database in the created region by passing its database URL in place of the database name on the db shell command.

turso db shell [database-url]

We can run some SQL scripts to see if our data is intact.
In fact, Turso first proxies the writes made to our replicas to our primary region and then replicate them in the replicas.

From the above output, we can see that everything has been synchronised.

Let’s try updating our Madrid database and then check the changes in our primary database.

Deleting a database replica from a region

If we do not need a Turso database replica in a certain region anymore, we can delete it by running the db destroy command, passing the name of the database followed by the id of the region on the --region flag.

turso db destroy todo --region mad

The above command deletes all replicas of a database we have in a selected region.

If we have multiple instances within a region and would like to specify the instance to delete, we need to add an --instance flag with the name of the instance to be deleted.

Summary

As explained, Turso is currently in early access (and will be until the end of March), meaning there will be some changes. For the moment, and with what I was able to examine and test, there’s so much promise. Creation limits are at the imagination of the builder (and the needs of the apps being built) because we have the sheer power of SQL queries at the tip of the edge.

I’ve barely scratched the surface here, we could have as sophisticated an example as possible with joins, unions, triggers, and all kinds of SQL functions(maybe in a future post), but learning SQL wasn’t the target of this one.
I was trying to examine this interesting tool, that the folks at ChiselStrike are trying to place in our hands.

To try Turso out, you can sign up for the early access program by going to their website - chiselstrike.com.

Nuxt 3 authentication with Supabase

James Sinkala — Sat, 04 Feb 2023 09:19:44 +0000

Supabase is the open-source Firebase alternative that presents us with back-end features such as a Postgres database, authentication, Edge functions, Storage, and Real-time subscriptions that we can use to build applications.

The interest of this tutorial is the authentication part, and, we are going to learn how to authenticate Nuxt 3 applications using Supabase.

To accomplish the task in this tutorial you need the latest LTS version of Node.js installed.
And, the source code to the project being created in this tutorial is available in this - GitHub repository.

Setting up the Nuxt project

If you are new to Nuxt 3 the getting started with Nuxt 3 tutorial will be a good place to start. Otherwise, run the following script on your terminal to scaffold a new Nuxt project.

npx nuxi init nuxt3-supabase-auth

The above script will scaffold a new Nuxt 3 app. Get into the project directory - cd nuxt-supabase-auth and create the following pages and components.

The login and index pages

Delete the default App.vue component scaffolded with the install script since it's of no use in this app's setup.

Create a /pages directory and in it add 3 page components - index.vue, register.vue, and login.vue. Add the following code to each respective page component.

Starting with the login.vue component, add the following code.

<script setup>
  const credentials = reactive({
    email: '',
    password: '',
  });
</script>

<template>
  <h1>Log in to your account!</h1>
  <form>
    <div>
      <label for="email">Email</label>
      <input type="email" id="email" v-model="credentials.email" />
    </div>
    <div>
      <label for="password">Password</label>
      <input type="password" id="password" v-model="credentials.password" />
    </div>
    <div>
      <button type="submit">Submit</button>
    </div>
  </form>
</template>

As for the register.vue component, add the following code.

<script setup>
  const credentials = reactive({
    firstName: '',
    surname: '',
    email: '',
    password: '',
    passwordRepeat: '',
  });
</script>

<template>
  <h1>Create an account!</h1>
  <form>
    <div>
      <label for="first-name">First Name</label>
      <input type="text" id="first-name" v-model="credentials.firstName" />
    </div>
    <div>
      <label for="surname">Surname</label>
      <input type="text" id="surname" v-model="credentials.surname" />
    </div>
    <div>
      <label for="email">Email</label>
      <input type="email" id="email" v-model="credentials.email" />
    </div>
    <div>
      <label for="password">Password</label>
      <input type="password" id="password" v-model="credentials.password" />
    </div>
    <div>
      <label for="password">Repeat Password</label>
      <input
        type="password"
        id="repeat-password"
        v-model="credentials.passwordRepeat"
      />
    </div>
    <div>
      <button type="submit">Submit</button>
    </div>
  </form>
</template>

And lastly, for the index.vue component that replaces the App.vue as the home page add the following code.

<template>
  <h1>Welcome to the dashboard!</h1>
</template>

Ideally, the home page of the app is supposed to be guarded against unauthenticated access, meaning, all unauthenticated users ought to be redirected to the login page.
To ensure this behavior, we will later create a guard that will take care of this.

Setting up the Supabase Nuxt 3 module

Next, integrate Supabase within the Nuxt 3 project.

Start by running the following script to install the Supabase module.

npm install -D @nuxtjs/supabase

Add the Supabase module to the Nuxt project's configuration - nuxt.config.js.

export default defineNuxtConfig({
  modules: ['@nuxtjs/supabase'],
});

The Supabase Nuxt module gives us access to the useSupabaseAuthClient, useSupabaseClient, and useSupabaseUser client-side Vue composables which can be utilized to achieve the goal within this tutorial.

Signing into the Nuxt 3 app

Inside the login.vue page, add a login function which with the assistance of the useSupabaseAuthClient() composable will set up the user sign-in logic.

// pages/login.vue

const client = useSupabaseAuthClient();
const router = useRouter();
const user = useSupabaseUser();

async function login() {
  const { email, password } = credentials;
  const { error } = await client.auth.signInWithPassword({ email, password });
  if (!error) return router.push('/');
  console.log(error);
}

watchEffect(async () => {
  if (user.value) {
    await router.push('/');
  }
});

Whenever issues arise with requests involved with the useSupabaseAuthClient()'s functions an error Object is always returned, else it is set to null.

In the above function when users are successfully authenticated the router is used to redirect them to the home page.

watchEffect is used in the above code to check if the user object is supplied by the useSupabaseUser() composable. This composable helps auto-import the authenticated Supabase user everywhere inside the Nuxt app. If the user is available as a result of a successful sign-in the app will redirect to the home page - /.

Registering users into the Nuxt 3 app

Inside the register.vue page, add a register() function that submits a registering user's details as filled in the provided form. The registration function's code is as follows.

// pages/register.vue

const client = useSupabaseAuthClient();

async function register() {
  const { firstName, surname, email, password, passwordRepeat } = credentials;
  if (password !== passwordRepeat) return;
  const { error } = await client.auth.signUp({
    email,
    password,
    options: {
      data: {
        first_name: firstName,
        surname,
        email,
      },
      emailRedirectTo: 'http://localhost:3000/login',
    },
  });
  if (error) {
    alert('Something went wrong !');
    return;
  }
  alert('Open the email we sent you to verify your account!');
}

As demonstrated previously with the signInWithPassword() function, the useSupabaseAuthClient() composable also gives access to a signUp function that takes some arguments the most important being the registering user's email and password.
In this example, an options object is also passed which enables the specification of the redirection URL - emailRedirectTo sent in the account verification email received by the registering user.
The data option specifies the extra information about the registering user being submitted along with the authentication credentials, in this case, the firstName and surname.

Up to this point, the app is not functional since the Supabase project credentials needed by the Nuxt module have not yet been provided, this will be done after having created a Supabase project.

Keeping unauthenticated users out

Before creating a Supabase project, an important piece of this app that was discussed above was the guarding of the home page from unauthorized access. This can be fulfilled by using a route middleware.
Set one up by creating a /middleware root folder and adding a auth.js file in it. Add the following code inside this file.

// middleware/auth.js
export default defineNuxtRouteMiddleware((to, _from) => {
  const user = userSupabaseUser();

  if (!user.value) {
    return navigateTo('/login');
  }
});

The above route middleware ensures that unauthorized sessions to pages it's applied to are redirected to the /login page.

To apply the middleware to a page, in this case, the home page the following code needs to be added.

// pages/index.vue

definePageMeta({
  middleware: 'auth',
});

Logging users out

To log users out of the Nuxt app the logOut() function of the useSupabaseAuthClient() composable needs to be called.

Create a /components root directory and in it add a Navbar.vue component with the following code.

// components/Navbar.vue

<script setup>
  const client = useSupabaseAuthClient();
  const user = useSupabaseUser();
  const router = useRouter();

  async function logOut() {
    const { error } = await client.auth.signOut();
    if (error) return;
    await router.push('/login');
  }
</script>

<template>
  <nav>
    <div>
      <button v-if="user" @click="logOut()">Log Out</button>
    </div>
    <div>
      <NuxtLink v-if="!user" to="/login">Login</NuxtLink>
    </div>
    <div>
      <NuxtLink v-if="!user" to="/register">Register</NuxtLink>
    </div>
  </nav>
</template>

In this component the /login and /register routes are exposed when a user is not authenticated, else the Log Out button is displayed.

The Log Out button calls the logOut() function that logs a user out and redirects the app to the /login page.

To bring all the parts of the UI together, create a default layout component by adding a /layouts root folder and adding a default.vue component adding the following code in it.

<template>
  <Navbar></Navbar>
  <slot></slot>
</template>

Now, the navigation bar together with its routes and buttons will be visible on every page depending on the authentication status of the app.

Setting up Supabase for a Nuxt 3 app

The second part of this tutorial involves creating a Supabase project.
To accomplish this, first, create a Supabase account.

After creating an account and completing the authentication process you'll end up in the Supabase dashboard. Create a new organization, then a new project.

After the project has been created, the proceeding page presents its details, amongst them its URL and key: anon public.

Create a .env file at the root of the Nuxt app, declaring a SUPABASE_URL and SUPABASE_KEY environmental variables in it, then populate them with the values obtained after the creation of the new Supabase project.

Setting up authentication within Supabase

Supabase provides a plethora of options to choose from when it comes to setting up user authentication. Users can be authenticated into an application by using various providers supported by Supabase's authentication as displayed in the figure below.

The above choice of providers can be viewed by going to Authentication > Providers within the Supabase dashboard.

By default, the email provider is enabled just as displayed in the above figure. The focus of this tutorial is on authenticating users into the Nuxt app created using the email method, so no changes are to be made here.

Supabase authentication credentials table

Supabase separates the authentication table from other data tables. On the event of registration of a user, the authentication credentials are placed inside the users table within the authentication section of the dashboard. Since no user has been registered, this table should be empty as demonstrated below.

Within the Supabase dashboard, tables and other elements can be created graphically or using SQL scripts inside the SQL editor.

Apart from the user authentication credentials that will be stored inside the users table in this demonstrational app, additional user data such as the first and surnames of registered users will need to be stored somewhere else. To do this, a table needs to be created that will hold this extra data.

Paste and run the following SQL script inside the SQL editor to create some tables, functions, and triggers.

create table profiles (
  id uuid references auth.users on delete cascade not null primary key,
  updated_at timestamp with time zone,
  email text,
  first_name text,
  surname text
);
create function public.handle_new_registration()
returns trigger as $$
begin
  insert into public.profiles (id, email, first_name, surname)
  values (new.id, new.raw_user_meta_data->>'email', new.raw_user_meta_data->>'first_name', new.raw_user_meta_data->>'surname');
  return new;
end;
$$ language plpgsql security definer;
create trigger on_new_user_created
  after insert on auth.users
  for each row execute procedure public.handle_new_registration();

A profiles table that will hold the user data discussed previously is created in the first part of the above SQL script. From the create function to $$ language plpgsql; part a Postgres function that creates a new record inside the profiles table whenever a new user is registered written in plpgsql is created.
Lastly, a trigger associated with the authentication - users table that calls the function above whenever a new record is added is also created.

The data passed as raw_user_meta_data inside the database function is obtained from what was passed inside the data option in the registration function created in the registration page - pages/register.vue.

Now, when a new user is registered, a new profiles table record will be created containing the fist_name, surname, and the email of the user as provided inside the registration form.

Summary

To summarize this tutorial, we have learned the following:

Using route middlewares to guard pages in Nuxt 3
Adding modules to Nuxt 3 apps
Setting up and using the Supabase Nuxt 3 module
Using the composables provided by the Supabase module to authenticate users in and out of a Nuxt 3 app
The creation of a Supabase project and integration into a Nuxt 3 app

To learn more about Nuxt 3 and Supabase, you can refer to their respective documentation:

Getting started with Nuxt 3

James Sinkala — Tue, 31 Jan 2023 21:17:30 +0000

In this post, we are going to learn about Nuxt, one of if not “the” most popular Vue.js frameworks.

To be specific, we are going to learn about Nuxt 3 - its latest release codenamed "Mount Hope".

As stated above, Nuxt is an open-source Vue.js framework for making websites, or to put it as its makers term it - "The intuitive Vue framework".

What is the difference between Vue.js and Nuxt?

Since Nuxt is a Vue framework, it means that we get several opinionated functionalities out of the box that we would otherwise not get inside a vanilla Vue.js app.

These preconfigured functionalities range from but are not limited to routing, app-level context, SSR(server-side rendering) & SSG(static site generation), inbuilt S.E.O (search engine optimization), data fetching, and several app-level configurations.
We can build vanilla Vue.js apps with such features, but that would involve setting everything up by ourselves either by using our own code or plug-in together some node modules.

So, in the name of not reinventing the wheel, let's learn about Nuxt and see what it offers.

N.B., before installing Nuxt just with Vue.js, you need to have node.js and npm installed in your system. A basic understanding of Vue.js will also be helpful since we’ll expansively be dealing with the Vue.js syntax.

Creating a new Nuxt project

Before creating a Nuxt project, you need to have the latest LTS version of Node.js installed on your system. The Visual Studio Code editor coupled with the Volar extension is a good setup for working on Nuxt.js projects.

To create a new Nuxt app named - getting-started-with-nuxt, run the following script on your terminal.

npx nuxi init getting-started-with-nuxt

Next, switch to the project's directory and run the npm install command on your terminal to install the project's dependencies.

# Switch into the project's directory
cd getting-started-with-nuxt

# install dependencies
npm install

Anatomy of a Nuxt application

After having created the new Nuxt app, when observing the project's file and directory layout, you should see the following:

getting-started-with-nuxt
  ├── README.md
  ├── app.vue
  ├── node_modules
  ├── nuxt.config.ts
  ├── package.json
  ├── pnpm-lock.yaml
  └── tsconfig.json

Let’s try to understand the files and directories that we see above.

app.vue: This is the main component of a Nuxt.js application created when you initiate a new project with npx nuxi init. This component is sufficient for an app that does not need routing.
node_modules: This is the file where the project’s dependencies are placed. We neither modify this directory’s contents nor stage its contents for versioning.
nuxt.config.js: This is the file that stores a Nuxt project's configuration.
package.json: Just as we will see in other JavaScript projects we'll be working on, the package.json file is the ID card of a project, carrying project details such as it's name, description, scripts, dependencies and so on. Visit the npm docs for more information about this file.
package-lock.json: This file persists the versions of the dependencies our project uses for consistency whenever our project happens to be run. We normally don’t modify this file as it is managed by the package manager. When using pnpm as your package manager, you will see a pnpm-lock.yaml instead.

To see what our project would look like when served, run npm run dev on your terminal.

Figure 1-1 is the presentation of what we should see if every step was correctly followed.

Nuxt pages and components

To add new pages to our Nuxt.js app we need to first create a /pages directory, then place all page files inside it. The /pages directory is optional in Nuxt 3. When it is present, Nuxt enables the support for its file-based routing, the opposite is true otherwise, unless we set pages: true inside the configuration file - nuxt.config.js or when a app/router.options.ts file is present.

Let's add the /pages directory to the Nuxt app we just created, transfer the app.vue file inside this directory and rename it to index.vue.

Visiting localhost:3000 after making the suggested change, we end up at the same point as we did in illustration 1-1.

Let's try visiting a new route - localhost:3000/new-page.
In doing so, we end up at the page illustrated below.

When we try to visit non-existent pages, Nuxt handles that by automatically directing us to a default 404 status page.
We can customize the error page by adding an error.vue component on the root of our project directory. We'll learn more about error handling on Nuxt in a later post.

Try renaming the index.vue component currently present inside the pages directory. When we try to visit localhost:3000, we end up at the error page displayed above once again. This is because each page that is created using a directory needs to have an index.vue component inside it that acts as the default view of that page, in our case, we are dealing with the website's homepage which is the root index.vue component found under the /pages top level directory.

Let’s add one more page to our Nuxt project.

Create a new about.vue component under the /pages directory adding the following template code inside.

<template>
  <div>
    <h1>This is the about page</h1>
  </div>
</template>

On your browser, visit the link - localhost:3000/about.
You should see the resulting page with the /about route as a page containing the title “This is the about page”.

Let’s see how we can use components in our Nuxt project.

In Nuxt, components are placed within the /components directory. We can then use them inside other components or pages.

Let's add a new component.
Inside the /components directory, add a new file, naming it - HighlightedText.vue. Add the following code inside the newly created component.

<template>
    <h2 style="font-weight: 800">
        "{{ text }}"
    </h2>
</template>
<script>
export default {
    props: {
        text: {
            type: String,
            default: "Some Message"
        }
    }
}
</script>

Next, import this component inside our about page currently at /pages/about.vue. We'll end up with the following after updating our about page.

<template>
  <div>
    <h1>This is the about page</h1>

    <HighlightedText></HighlightedText>
  </div>
</template>

<script>
import HighlightedText from '../components/HighlightedText.vue';
export default {
  components: {HighlightedText}
}
</script>

On visiting the about page route again, we'll see the "some Message" text rendered as expected.

Try deleting the component-importing code from the about.vue file, remaining with the following code.

<template>
  <div>
    <h1>This is the about page</h1>

    <HighlightedText></HighlightedText>
  </div>
</template>

When you visit localhost:3000/about again, nothing would have changed, you'll still see the "Some Message" text present, meaning that our component is still rendered despite removing the component importation code.

So, what happened?

The explanation for this behaviour is simple. Nuxt scans the /component directory by default and makes all found components globally available for consumption within other components and pages, abstaining us from the need to import them every time we need to use them. This helps us write less code.

This completes the introductory part of Nuxt 3. The source code for the project we created in this post is available on this GitHub repository.

Summary

We have so far learnt how to create a new Nuxt 3 project, what a Nuxt project’s various files and directories represent, see how we can create new pages, and use components inside Nuxt pages.

This post has been a mere introduction to Nuxt 3, we'll see more of what we can do with pages and components in future posts. We’ll also be covering more Nuxt concepts intuitively by working on real-world projects.

To learn more about Nuxt 3 - visit the official docs.

Vue.js directives: Form binding and event handling

James Sinkala — Thu, 22 Dec 2022 17:54:01 +0000

One of the most important activities in web applications is form interaction. We use forms for user authentication, providing feedback in the form of comments and answering online questionnaires, rating things such as books or contributing to polls, filling in address information on e-commerce websites, writing e-mails, and the list goes on.

Such user interaction in web apps which to a large extent involves forms proves their superiority since they possess features beyond presentational capabilities where data flows in one direction only. Businesses would get responsive feedback from their customers or even go as far as communicating with their customers when using chat tools embedded on customer-care web pages. The same couldn't be said of media such as magazines or TV ads.

The v-model directive

Vue.js enables us to manipulate form data via the special directive v-model. The v-model is different from the v-bind directive since it supports two-way data binding, meaning, data can be updated in both the presentational part, in this case, the template form fields, and the controller part of the app instance.

Let's see an example using the v-model directive.

<html>
  <div id="app">
    <h2>Login Form</h2>
    <form>
      <input type="text" v-model="msg">
      <br>
      {{ msg }}
    </form>
  </div>

  <script src="/js/vue.global.js"></script>
  <script>
    let app = Vue.createApp({
      data() {
        return {
          msg: "Hello, World!"
        }
      }
    }).mount("#app");
  </script>
</html>

Try to edit the message inside the input field in the above example to see it getting updated on the mustache output.

Trying to update the msg field inside our Vue.js instance above will also update the form field. Add the following code to the JavaScript above to see the changes.

mounted(){
  let addRandomText = () => {
    this.msg = this.msg + " other text!"
  }
  setTimeout(addRandomText, 3000);
}

So, not only can data be updated from the two parts of our app, the variable also stays in sync in both parts, i.e. changes to the variable from the template are reflected by it inside the Vue.js instance and vice-versa.

Binding form text input

Binding form text is as straightforward as demonstrated in the above example, you need to initiate the variable inside the data property and bind it to the v-model directive on the input element.

Let's see another example using the textarea form field.

  <textarea v-model="longMsg"></textarea>
  <br>
  {{ longMsg }}

return {
  msg: "Hello, World!",
  longMsg: "This is a very loooooooooooooooooooooooooooooooooooooooooooooooooooooooong paragraph."
}

Add the above code to the respective template and JavaScript parts of the previous example.

Binding form number input

To bind numbers in form input fields you need to set the type to "number" and append .number to the v-model directive, making sure you initiate the number variable inside the data property with a variable of the Number type.

Let's see a number input example.

  <input type="number" v-model="someNumber">
  <br>
  {{ someNumber }}
{{ longMsg }}

return {
  someNumber: 0,
}

Binding form select fields

With select form fields, add the v-model directive with the data property variable in the select field. When an option is selected from the select field, the String or Number set on the value attribute of the option element is assigned to the variable, otherwise, the label is selected.

<select id="age-select" v-model="selectedAge">
  <option v-for="item in options" :value="item.key">{{ item.label }}</option>
</select>
<br>
{{ selectedAge }}

return {
    options: [{key: 12, label: '12yrs'}, {key: 14, label: '14 yrs'}],
    selectedAge: 0
}

Binding form input radio fields

With form radio inputs, you set the values of the dial input fields to the exact variable you want the bound data property to be set to when a radio choice is selected. You should bind the same data property to all of the radio fields belonging to the same query.

<label for="dials">Are you a Vue Noob?</label>
<label>
  <input type="radio" id="dials" v-model="isANoob" value="Yes I am"> Yes
</label>
<label>
  <input type="radio" id="dials" v-model="isANoob" value="Not I'm not"> No
</label>
<br>
{{ isANoob }}

return {
  isANoob: "Yes I am",
}

It's good practice to initiate radio field data variables with a default choice so as not to receive undesired data submissions.

Binding form checkboxes

Since checkbox checks resolve to a true when checked and false when unchecked, unlike the dial input, all check options should be assigned to separate variables.

Here's a checkbox example.

<label for="chk-one">What Web technologies are you familiar with?</label>
<label>
    <input type="checkbox" v-model="chkOne"> HTML
</label>
<label>
    <input type="checkbox" v-model="chkTwo"> JavaScript
</label>
<label>
    <input type="checkbox" v-model="chkThree"> CSS
</label>
<br>
HTML: {{ chkOne }} JavaScript: {{ chkTwo }} CSS: {{ chkThree }}

return {
  chkOne: true,
  chkTwo: false,
  chkThree: false
}

While dealing with HTML forms, when users have completed filling in the required information we usually expect some action to be performed to proceed with the next desired steps. Normally when HTML forms are submitted via an input field with the type="submit" or a button click, the page sends the form data to the URL provided in the action attribute using the HTTP method provided in the method form attribute followed by a page reload or redirection to a URL, all depending on the response it receives from the back-end in question.

In Vue.js, just as with most front-end JavaScript environments, we do not favour the page refreshes as those would certainly mess up our app states.

Let's demonstrate this in an example.

<html>
  <div id="app">
    <form>
      <input type="text" v-model="name">
      <br>
      <button type="submit">Submit</button>
    </form>
  </div>

  <script src="/js/vue.global.js"></script>
  <script>
    let app = Vue.createApp({
      data() {
        return {
          name: "Noob",
        }
      }
    }).mount("#app");
  </script>
</html>

Clicking "Submit" in the above example refreshes the page, and we lose the number that we had before after the title - "Cool Form".

In JavaScript front-end frameworks we are usually submitting form data to remote back-ends through API endpoints, then carry on with the next steps depending on the responses we receive without refreshing the page, keeping the rest of the app state intact.

Event handling in Vue

To carry out form submissions, we need to listen to button click events and call some functions that process and submit this data to where it needs to go.

In Vue.js, event listening on HTML elements is performed through the v-on directive. Just as in the case with the v-bind directive, we add the v-on directive as a prefix to element events separated by a colon, removing the "on" usually found on elements' event attributes, meaning, when a button onclick attribute fires in response to a button click event, we perform a method call - onclick="function()". In Vue.js templates, we would have the regular event attributes only replacing the on in the beginning with v-on:.

Let's see an example.

<html>
  <div id="app">
    <h2>Count: {{ num }}</h2>
    <button v-on:click="num++">Increment</button>
  </div>

  <script src="/js/vue.global.js"></script>
  <script>
    let app = Vue.createApp({
      data() {
        return {
          num: 0,
        }
      }
    }).mount("#app");
  </script>
</html>

In the above example, we increment the value of num by one each time the button is clicked, we do that by resolving the JavaScript expression num++ inside v-on:click .

Let's see another example.

<input type="text" v-model="text" v-on:blur="text = text + ' a'">

data() {
  return {
    text: 'Hello!'
  }
}

Try clicking in and out of the above input field to see what happens.

In both cases, when the click and blur events are fired, the JavaScript expressions are resolved.

Unlike the mustache syntax which is used for presentational purposes, the v-on directive can run JavaScript expressions and update our data properties values as demonstrated in the above examples.

The v-on shorthand

Just like Vue.js provides the colon : as the shorthand for the v-bind directive, it also provides an "at" sign - @ as the shorthand for the v-on directive. So, instead of using the long v-on in the above examples, we can shorten the code by using the @, ending up with.

<button @click="num++">Increment</button>

<input type="text" v-model="text" @blur="text = text + ' a'">

We will be using the shorthand version of the v-on directive here-onwards.

We have already seen how we can execute JavaScript expressions inside the v-on directive, next, we are going to see how we can call functions with it. Let's first see how to initiate functions in Vue.js.

Methods in Vue

Methods or functions in Vue.js are initiated inside the "methods" option of the Vue.js instance. Just as we've seen with the data properties, we add "methods" directly as a property of the Object passed inside createApp() with all our functions as the direct properties of this "method" Object.

Moving the in-line expressions in the previous example into individual methods, we can then proceed to make function calls reducing the logic within our template as follows.

<html>
  <div id="app">
    <h2>Count: {{ num }}</h2>
    <button @click="increment()">Increment</button>
    <hr>
    <input type="text" v-model="text" @blur="appendText()">
    <hr>
    num + length of text: {{ numPlusText }}
  </div>

  <script src="/js/vue.global.js"></script>
  <script>
    let app = Vue.createApp({
      data() {
        return {
          num: 0,
          text: 'Hello!'
        }
      },
      computed: {
        numPlusText(){
          return this.num + this.text.length;
          console.log(this.numPlusText);
        }
      },
      methods: {
        increment(val){
          this.num++
        },
        appendText(){
          this.text = this.text + ' a';
          console.log(this.numPlusText);
        }
      }
    }).mount("#app");
  </script>
</html>

In contrast to computed properties, methods do not cache their results, updates can be made to variables within them, and even DOM mutating operations can be performed within them.

N.B., Each time a method is invoked, all of the operations inside it are performed. Due to this, it is a good practice to perform expensive operations that don't involve non-reactive dependencies such as Date.now() and Math.random() inside computed properties.

Inside Vue.js methods, we can access all the data and computed properties inside this as demonstrated above.

Open your browser's console log to see the computed property value numPlusText being logged out whenever the two functions above are called.

Completing form operations

Bringing together all of what we have learned in this post let's set up a login form, and submit its data when a button click attribute event is fired, calling a specific login method that validates our form data before sending it to the external API endpoint.

<html>
  <div id="app">
    <div v-if="!loggedIn">
      <h2>User Login</h2>
      <br>
      <form action="">
        <p v-show="validationError">Error: {{ validationError }}</p>
        <label for="email">Email: </label>
        <input type="email" id="email" v-model="email" required>
        <br>
        <br>
        <label for="password">Password: </label>
        <input type="text" id="password" v-model="password" required>
        <br>
        <br>
        <button @click.prevent="logIn()">{{ loading ? 'loading..' : 'Log In' }}</button>
      </form>
    </div>

    <div v-else>
      <h2>Use Dashboard</h2>
      <p>Successfully Logged In!</p>
    </div>
  </div>

  <script src="/js/vue.global.js"></script>
  <script>
    let app = Vue.createApp({
      data() {
        return {
          email: "",
          password: "",
          loggedIn: false,
          validationError: "",
          loading: false
        }
      },
      methods: {
        logIn(){
          this.validationError = "";
          let errorsCount = 0;
          if(this.password.length < 4){
            this.validationError = "Password is not valid";
            errorsCount++;
          }
          const simulateAuthentication = () => {
            this.loading = false;
            this.loggedIn = true;
          }
          if(errorsCount === 0){
            this.loading = true;
            setTimeout(simulateAuthentication, 3500);
          }
        }
      }
    }).mount("#app");
  </script>
</html>

When you submit the above form after filling in the required fields correctly, you will experience a page refresh and lose the app state that helps our app run correctly. This is the default HTML form behavior as explained above, it is not "a bug" in Vue.js.

Usually, when intending to make JavaScript HTTP requests instead of using the form element default behavior to perform form data submissions, we prevent it by calling preventDefault() of the Event interface inside our control functions. To prevent the default form behavior in the case of Vue.js, we append the suffix .prevent at the end of our event listener @click, ending up with @click.prevent="logIn()".

Perform this change to the above code to fix the reload issue.

In the example above, we are simulating the login process with a timer function, in real life applications we use HTTP clients to make these calls and process all of the possible responses that we might receive from the remote back-ends.

Vue.js Directives: Data Binding in Vue

James Sinkala — Sat, 08 Oct 2022 13:42:51 +0000

Making the front-end dynamic in web development involves logic that reorganizes or rewrites various nodes of the HTML DOM tree. In simple terms, the HTML in our pages needs to be updated or changed without triggering page reloads.

In Vue.js, this is made possible by directly binding the target HTML tag's inner content, attributes, and events to the Vue.js instance with the help of its custom directives.

These Vue.js directives help us apply JavaScript operations directly on the template HTML while Vue.js handles the nitty-gritty work we'd normally do in vanilla JavaScript under the hood, simplifying the whole development process for us.

Custom Vue.js Directives

Vue.js has a number of these custom directives that assist us in making the HTML markup in our templates dynamic. Let's get acquainted to some of them through simple demonstrations.

Take a look at the following example.

<html>
  <style>
    .box {
      background-color: coral;
      width: 100px;
      height: 100px;
      margin: 20px;
    }
  </style>
  <div id="app">
    <div class="box" v-show="showBox"></div>
  </div>
  <script src="https://unpkg.com/vue@3"></script>
  <script>
    let app = Vue.createApp({
      data() {
        return {
          showBox: true,
        };
      },
      mounted() {
        const toggleVisibility = () => {
          this.showBox = !this.showBox;
        };
        let intervalId = setInterval(toggleVisibility, 1000);
        const stopToggle = () => {
          this.showBox = true;
          clearInterval(intervalId);
        };
        let timeoutId = setTimeout(stopToggle, 20000);
      },
    }).mount('#app');
  </script>
</html>

When you open the above example on your browser, you'll see a color box appearing and disappearing for a span of 20 seconds.

The v-show directive

We achieve this blinking effect by toggling the state of the showBox variable between the true and false states. We can find this in the logic defined in the mounted hook. And to bind that state to our box (the div block with the .box class) we use the v-show Vue.js directive on it.

The v-show is a custom Vue.js directive that modifies the display style of a HTML element based on the truthiness of the variable passed to it. If it's an expression or value that is falsy, it adds a display: none style to the HTML element in question.

v-show is among Vue.js' conditional directives, i.e. directives that fulfill a task based on the truthiness of the value being observed. Other conditional Vue.js directives include v-if, v-else-if, and v-else. We will look at these in more depth later.

The v-bind directive

Let's take a look at another example.

<html>
  <style>
    meter {
      height: 3em;
      width: 15em;
    }
  </style>

  <div id="app">
    <h1>Vue City Water Flow Rate Levels</h1>
    <h2>({{'{{'}} level.toFixed() {{'}}'}} m³/hour)</h2>
    <meter
      min="0"
      max="100"
      low="33"
      high="66"
      optimum="80"
      v-bind:value="level"
    ></meter>
    <br />
  </div>
  <script src="https://unpkg.com/vue@3"></script>
  <script>
    let app = Vue.createApp({
      data() {
        return {
          level: 0,
        };
      },
      mounted() {
        const fluctuateLevel = () => {
          this.level = Math.random() * 15 + 60;
        };
        let intervalId = setInterval(fluctuateLevel, 200);
      },
    }).mount('#app');
  </script>
</html>

In the above example, we are observing the fluctuating water flow rate in our imaginary city - "Vue City".

As evident, we are simulating the water levels between values 60 and 75 inside the fluctuateLevel() function inside the mounted hook.

To succeed in our demonstration, we need to make sure that the value attribute of the meter element keeps changing by being updated by the value of the level Vue.js variable. We achieve this by attaching the v-bind directive whose function is to bind the values of reactive Vue.js variables to HTML element attributes, in our case the level variable to the value attribute of the meter element (v-bind:value="level"). Hence, whenever level changes, the element's attribute immediately gets the updated value, in-turn updating the meter we see on the page.

Binding HTML with the v-html directive

Not only does Vue.js support binding for plain variables, but it also has a custom directive that handles the binding for HTML markup, the v-html.

This directive can be quite handy when trying to display content such as a blog's article content fetched from an external data API.

Let's demonstrate this in an example.

<html>
  <div id="app">
    <h1>{{'{{'}} title {{'}}'}}</h1>
    <div>
      <h2>With v-html</h2>
      <article v-html="htmlContent"></article>
    </div>
    <div>
      <h2>without v-html</h2>
      <article> {{'{{'}} htmlContent {{'}}'}} </article>
    </div>
  </div>
  <script src="https://unpkg.com/vue@3"></script>
  <script>
    let app = Vue.createApp({
      data() {
        return {
          title: '',
          htmlContent: ''
        }
      },
      async mounted() {
        await fetch('https://hacker-news.firebaseio.com/v0/item/121003.json?print=pretty')
          .then((res) => res.json())
          .then((res) => {
            console.log(res);
            this.htmlContent = res.text;
            this.title = res.title;
          })
      },
    }).mount("#app");
  </script>
</html>

In the example above, we are fetching data from the Hacker news API and extracting a title and text containing HTML tags.
Trying to render the HTML content inside the htmlContent variable inside the mustache syntax as seen in the first section does not give us intended results as the HTML content is plotted as is. This is not what we want to see in such a case.
Binding the same variable onto the second article tag using the v-html directive gives us what we want, having the HTML inside our variable rendered as part of the existing page template.

The asynchronous fetch method above is nothing other than a helper that is assisting us in fetching remote data. You can read more about the fetch API here.

We will cover more tutorials involving fetching data from external data API in the future. This is just a simple example demonstrating the gist of it.

After getting introduced to Vue.js directives, we'll be going in depth on conditional and list rendering inside Vue.js templates while using them in the next post.

DEV Community: James Sinkala

Create a distributed API for your e-commerce store using Cloudflare and Turso

Creating a new Cloudflare workers project

Creating a Turso database

Handling endpoints with a router

Setting up Drizzle as the ORM tool for the project.

Create and generate database schemas using Drizzle.

A/B testing use case with Turso

Getting started

Setting up Turso

Setting up GrowthBook

Setting up A/B experiments on GrowthBook

Configure GrowthBook on Next.js’ edge middleware

Displaying features on the client

Create a shopping cart using Qwik and Turso

Why build a shopping cart with Qwik and Turso?

Building the shopping cart

Product listing

The cart

Checkout

Order placement

Deploying a web app built with Qwik and Turso on Netlify

Anatomy of the application

Setting up Turso

Deploying the app on Netlify

Creating Netlify Edge functions

Deploying the app

Creating a newsletter manager with Turso and Qwik

Newsletter platforms are either unreliable or expensive, here’s why I rolled my own

Creating the newsletter manager with Turso and Qwik

Setting up the Turso database

The Qwik app

The newsletter home page

The newsletter admin page

The newsletter unsubscription page

Creating A Hot New Food Delivery App with Novu

TL;DR

Join the ConnectNovu Hackathon

The Kick-Off

Jumping Into Business

Getting Our Project Started

Setting Up PostMark

Creating Notifications on Novu

Send A Welcome Notification

Integrating Novu into Foody

Sending Order-Specific Notifications with Novu

Sending Order Confirmations

Sending Delivery Status Notifications

Sending Bulk Subscription-based Notifications With Novu Topics

Creating a Novu Topic

Adding New Subscribers And Sending Notifications

Customizing Notification Options

The Wrap-Up

Understanding Vue.js Single-File Components (SFCs)

Working with Vue.js Single-File Components(SFCs)

Anatomy of a Vue.js SFC file

The <script setup> sugar syntax in Vue.js SFCs

Binding SFC component state to styles

Summary

Early impressions of Turso, the edge database from ChiselStrike

Installing Turso

Creating a new database

Choosing the primary database region

Creating database tables

Submitting data to a Turso database

Replicating a Turso database into other regions

Deleting a database replica from a region

Summary

Nuxt 3 authentication with Supabase

Setting up the Nuxt project

The login and index pages

Setting up the Supabase Nuxt 3 module

Signing into the Nuxt 3 app

Registering users into the Nuxt 3 app

Keeping unauthenticated users out

Logging users out

Setting up Supabase for a Nuxt 3 app

Setting up authentication within Supabase

Supabase authentication credentials table

Summary

The `<script setup>` sugar syntax in Vue.js SFCs