DEV Community: Xkonti

Adding Mermaid diagrams to Astro MDX

Xkonti — Fri, 05 Jul 2024 21:17:34 +0000

Adding Mermaid diagrams to Astro pages has a surprising number of challenges. Most of the solutions out there rely on using headless browsers to render the diagrams. This approach has a few drawbacks:

You need to install a headless browser on your machine to be able to build your site
It might prevent your site from building on CI/CD (like Cloudflare Pages)
It might slow down your site's build time significantly

The reason for the popularity of this approach is that Mermaid.js relies on browser APIs to lay the diagrams out. Astro doesn't have access to these APIs, so it can't render the diagrams directly.

Fortunately, there's another option: rendering the diagrams on the client side. Definitely not ideal, as suddenly our pages won't be fully pre-rendered, but in case only some of your pages have diagrams, it's still a viable option. Especially that it doesn't require any additional setup.

High level overview

The idea is to use the official mermaid package directly and let it render the diagrams on the client side. In my case I want to have a diagram as a separate component to add some additional functionality, like the ability to display the diagram's source code. This decision has one side effect: The component won't work in pure Markdown files. It will only work in MDX files.

To make it work in pure Markdown files, one would need to create a rehype/remark plugin, but I didn't feel like it was worth the effort - I use MDX files for everything as it provides more functionality.

Building the component

First we need to install the mermaid package:

# npm
npm install mermaid

# pnpm
pnpm add mermaid

Now let's create the component. It will be an Astro component as we don't need any additional framework functionality for this. Let's call it Mermaid.astro - I placed in in stc/components/markdown folder:

---
export interface Props {
  title?: string;
}
const { title = "" } = Astro.props;
---
<script>
import mermaid from "mermaid";
</script>

<figure>
  <figcaption>{title}</figcaption>
  <pre class="mermaid not-prose">
    <slot />
  </pre>
</figure>

Nothing special here:

We make the component accept a title prop so that we can display a nice title - relying on mermaid's built-in titles itn't optimal as the title will show up in various sizes depending on the diagram's size.
We add a script that will import the mermaid package on the client side. It's worth noting that Astro will include that script only once on the page no matter how many times we use the component. Simply including the mermaid will register a DOMContentLoaded event listener for the mermaid renderer.
The mermaid renderer looks through the entire page for <pre> elements with the mermaid class. Including it here will ensure that the diagram code will be processed by mermaid. In my case I also need to add the not-prose class to remove some conflicts with my markdown styling.
The <slot /> element will be replaced with the mermaid code wrapped by this component.

Now let's try to use it in an MDX file:

---
title: Testing mermaid in Astro
---

import Mermaid from "@components/markdown/Mermaid.astro";

<Mermaid title="Does it work?">
flowchart LR
    Start --> Stop
</Mermaid>

And the results is:

This is where inspecting the page source comes in handy. This way we can see what Astro rendered before mermaid tried to process it:

<figure>
  <figcaption>Does it work?</figcaption>
  <pre class="mermaid not-prose">
    <p>flowchart LR
Start —&gt; Stop</p>
  </pre>
</figure>

There are several issues here:

Our code is wrapped in <p> tag, confusing the hell out of mermaid
The double dash -- has been replaced with an em dash — which is not what mermaid expects
The > character has been replaced with > which messes thing up even more

What could have caused this? Markdown.

When the MDX page is rendered, all that is not explicitly an MDX element, is processed by markdown. This includes everything wrapped in the <Mermaid> component. Markdown saw some text - it marked it as a paragraph, escaped the scary characters (>), and then prettyfied it by consolidating the dashes.

Solving the issue

There are several ways to solve this issue:

Pass the code as a string to the component - deal with manually adding \n to simulate new lines as HTML doesn't support multiline arguments.
Load the diagrams as separate files using the import statement - don't have everything in one place.
Go the crazy route and pass a code block to the component 🤪

Of course I went for the last one. It might sound like a great idea, but depending on the way
your setup renders the code blocks, it might be a bit of a pain to deal with. Let's try it:

---
title: Testing mermaid in Astro
---

import Mermaid from "@components/markdown/Mermaid.astro";

<Mermaid title="Does it work?">
`` `mermaid
flowchart LR
    Start --> Stop
`` `
</Mermaid>

⚠️ Please remove the extra space from triple backticks - dev.to has really bad code block support that doesn't allow nesting. Consider reading this article on my website.

My blog uses Expressive Code] to render the code blocks, and therefore the page's source code will look like this:

<figure>
  <figcaption>Does it work?</figcaption>
  <pre class="mermaid not-prose">
    <div class="expressive-code">
      <figure class="frame">
        <figcaption class="header"></figcaption>
        <pre data-language="mermaid">
          <code>
            <div class="ec-line">
              <div class="code">
                <span style="--0:#B392F0;--1:#24292E">flowchart LR</span>
              </div>
            </div>
            <div class="ec-line">
              <div class="code">
                <span class="indent">
                  <span style="--0:#B392F0;--1:#24292E">    </span>
                </span>
                <span style="--0:#B392F0;--1:#24292E">Start --&gt; Stop</span>
              </div>
            </div>
          </code>
        </pre>
        <div class="copy">
          <button
            title="Copy to clipboard"
            data-copied="Copied!"
            data-code="flowchart LR    Start --> Stop"
          >
            <div></div>
          </button>
        </div>
      </figure>
    </div>
  </pre>
</figure>

Wow. This added a bit more markup to the page... but what's that? A copy button? How does that work? Take a look at it's markup:

<button
  title="Copy to clipboard"
  data-copied="Copied!"
  data-code="flowchart LR    Start --> Stop"
>
  <div></div>
</button>

That's the whole source code of our diagram in a pleasant HTML argument string. It's easy to extract it and give it to mermaid on the client side. Let's modify our Mermaid.astro component to do exactly that!

No copy button?
If you're not using Expressive Code and your code blocks don't have the handy copy button, I included an alternative code snipped at the end of the article.

Preparing the component

First, let's rework the component's HTML markup. We'll wrap it in a figure element and place the code block indside a details element. This way we can hide the code block by default and show it only when the user clicks on the Source button.

...
<figure class="expandable-diagram">
  <figcaption>{title}</figcaption>

  <div class="diagram-content">Loading diagram...</div>

  <details>
    <summary>Source</summary>
    <slot />
  </details>
</figure>

The whole component is wrapped in a figure element with a expandable-diagram class. This way we can easily find all instances of the component using CSS selectors.
The div.diagram-content element is where the diagram will be rendered.
The source buggon needs to be clicked by the user to reveal the code block.
The slot element will be replaced with the code block rendered by Expressive Code.

Extracting the source code

Now let's rewrite our script to extract the code from the copy button and place it in the
.diagram-content element:

...
<script>
  import mermaid from "mermaid";
  // Postpone mermaid initialization
  mermaid.initialize({ startOnLoad: false });

  function extractMermaidCode() {
    // Find all mermaid components
    const mermaidElements = document.querySelectorAll("figure.expandable-diagram");
    mermaidElements.forEach((element) => {
      // Find the `copy` button for each component
      const copyButton = element.querySelector(".copy button"); 
      // Extract the code from the `data-code` attribute
      let code = copyButton.dataset.code;
      // Replace the U+007f character with `\n` to simulate new lines
      code = code.replace(/\u007F/g, "\n");
      // Construct the `pre` element for the diagram code
      const preElement = document.createElement("pre");
      preElement.className = "mermaid not-prose";
      preElement.innerHTML = code;
      // Find the diagram content container and override it's content
      const diagramContainer = element.querySelector(".diagram-content");
      diagramContainer.replaceChild(preElement, diagramContainer.firstChild);
    });
  }

  // Wait for the DOM to be fully loaded
  document.addEventListener("DOMContentLoaded", async () => {
    extractMermaidCode();
    mermaid.initialize({ startOnLoad: true });
  });
</script>
...

A lot is happening here, so let's break it down:

To prevent mermaid from processing the diagrams instantly, we need to postpone it's initialization.
We define the extractMermaidCode function to keep things somewhat organized.
The script will be executed only once per page, so we need to find all instances of our Mermaid component. This way we can process them all at once.
Once we're in our component, we can easily find the copy button as there's only one.
Extracting the code is relatively simple.
Of course there's one more catch. The copy button contains a data-code attribute with the new lines replaces with U+007f character. We need to replace it with \n for mermaid to understand it.
Now that we have the code, we can create a new pre element with mermaid class. This is what the mermaid library will look for to render the diagram from.
We can replace the existing diagram content (Loading diagram...) with the newly created pre element.
We register our own DOMContentLoaded event listener that will allow us to run code only once the page is fully loaded.
Finally, we call our extractMermaidCode function to prep the HTML for mermaid and render the diagrams.

Phew! What was a lot of code, but it's not the worst. Let's save it and refgresh the page:

That's much better! The only thing left is to modify it a bit to make it look better. This is after a light dressing up with Tailwind to fit this blog's theme:

In case you're not using Expressive Code

If you're not using Expressive Code and your code blocks don't have the copy button, there's always a different way. I know it sounds crazy, but you could try to go over all the spans rendered by the code block and collect the characters from there. After some fiddling with ChatGPT, here's an example of this approach in action that worked for well me:

...
<script>
import mermaid from "mermaid";
mermaid.initialize({ startOnLoad: false });

function extractAndCleanMermaidCode() {
  const mermaidElements = document.querySelectorAll("figure.expandable-diagram");
  mermaidElements.forEach((element) => {
    // Find the code element within the complex structure
    const codeElement = element.querySelector(
      'pre[data-language="mermaid"] code'
    );
    if (!codeElement) return;

    // Extract the text content from each line div
    const codeLines = codeElement.querySelectorAll(".ec-line .code");
    let cleanedCode = Array.from(codeLines)
      .map((line) => line.textContent.trim())
      .join("\n");

    // Remove any leading/trailing whitespace
    cleanedCode = cleanedCode.trim();

    // Create a new pre element with just the cleaned code
    const newPreElement = document.createElement("pre");
    newPreElement.className = "mermaid not-prose";
    newPreElement.textContent = cleanedCode;

    // Find the diagram content container
    const diagramContentContainer = element.querySelector(".diagram-content");

    // Replace existing diagram content child with the new pre element
    diagramContentContainer.replaceChild(newPreElement, diagramContentContainer.firstChild);
  });
}

// Wait for the DOM to be fully loaded
document.addEventListener("DOMContentLoaded", async () => {
  extractAndCleanMermaidCode();
  mermaid.initialize({startOnLoad: true});
});
</script>
...

I hope this will help you out in marrying Astro with Mermaid.js.

Creating GPT Actions with ValTown

Xkonti — Sun, 26 May 2024 05:44:39 +0000

Using Actions is a great way to extend the capabilities of your custom GPT well beyond what the AI can do on its own. Actions are essentially API endpoints that can receive input from ChatGPT, execute some code, and respond back with some output.

Creating an API endpoint for GPT actions might seem complicated, involving setting up a complex project, purchasing and configuring a server, hassling with a lot of HTTP intricacies, and so on. However, with ValTown, it's actually quite simple and totally free. In this article, I'll show you how to create a simple action for your custom GPT using ValTown, step by step.

Disclaimer:
This article assumes that you can create your own GPTs. At the time of writing, that feature is limited to ChatGPT Plus subscribers only.

ℹ️ The version of the article on my blog has code snippets with specific lines highlighted so that it's easier to follow the tutorial.

What we're going to build

We're going to create a simple GPT. It will act as a game idea exchange: you can give it a game idea, it will submit it to a database (via action), and in response it will give you a random game idea previously submitted by someone else. Consider it a multiplayer GPT.

Here's what it looks like in action:

You can check out the finished GPT here.

We'll follow these steps:

Create a new GPT with complete instructions
Create an endpoint for the action using ValTown
Point GPT to the API
Develop the internal functionality of the action
Test the GPT
Update the existing action with extra functionality
Secure the API with an API key
Attach privacy policy to your API

Creating Game idea exchange GPT

Let's start by creating a new GPT so that we have something to work with. Go to the GPT editor, give it a name, a description, and instructions. Here's what I used:

Name: Game idea exchange
Description: Exchange video game ideas with other people!
Instructions:

   Act as a Fun Video Game Idea broker. Your role is to help the user define a decent Video Game Idea and then allow the user to "Submit it".

   # Submitting the Fun Video Game Idea

   To submit the Video Game Idea, there are 2 things needed:
   - At least 3-sentence idea for a video game - user needs to approve it first - asking for submission is equal to approval
   - A name the creator wants to be referred by - ask for it

   The Video Game Idea has to be submitted using the `submitidea` action. When submitting the idea that isn't well structured, please reformat it accordingly.

   Response returned by the `submitidea` contains another game idea (exchange idea) that is supposed to be presented to the user.

Conversation starters:
- My idea:
- Can you help me come up with some game ideas?

The instructions mention a submitidea action. This tells ChatGPT when to use that specific action. We'll create that action in the next step.

Pro-tip:
I recommend disabling web browsing, image generation, and the code interpreter. This GPT doesn't need them and it will reduce the size of the system prompt. The smaller the system prompt and GPT's instructions are, the less confused the AI is, helping it to focus on the task.

Creating action endpoint in ValTown

ValTown describes itself with the following words:

If GitHub Gists could run and AWS Lambda was fun.
Val Town is a social website to write and deploy TypeScript. Build APIs and schedule functions from your browser.

ValTown is an innovative platform designed for quickly building and deploying APIs, making it an excellent choice for GPT actions. Here's why:

Ease of Setup: No complex hosting or environment setup required. You can write, test, and deploy code directly in your browser.
Free Usage: Ideal for small projects and experimentation without any cost. This includes a key-value store and a SQLite database 💪
In-Browser Coding: Fully integrated TypeScript editor with code completions and AI assistant (Codeium), vastly simplifying the development experience.
Supportive Community: Has a very active and supportive community. Check out their Discord server for help and inspiration.

Creating a new Val

Create an account on ValTown if you haven't already. Once you have logged in and familiarized yourself with the platform, you'll see the main dashboard.

The first thing we need is a Val - basically a snippet of code that ValTown can run. It's similar to a GitHub Gist but with the ability to run code.

In the Create a new val section, click on the HTTP handler button:

A brand new Val will be created. The Val is instantly ready to handle HTTP requests. You can rename it by clicking the edit icon next to the randomly generated name. That name will be a part of the URL used to access the API.

Warning:
Please limit it to alphanumeric characters as actions often break when encountering special characters.

There are a few things to point out here:

Under the name, you can see that the Val is marked with an HTTP label - this tells ValTown to treat it as an API endpoint, and therefore allows it to be accessed via HTTP requests.
The visibility is set to Unlisted - this means that the Val is not searchable and only people with a link can access it. This setting also allows external HTTP requests to be sent to it.

You can change it to Public if you want to share it with others. If you set it to Private, only you will be able to access it. Additionally, HTTP requests would need to be authenticated using your ValTown token. Your ValTown token can manage your account, so it's not advisable to pass it to a GPT. We'll handle protecting endpoints later.

Under Browser preview you can see the URL that points to the Val. This is the URL that you'll give to the GPT to send HTTP requests to.

ValTown automatically places some boilerplate code in the editor. This is a generic HTTP handler that returns simple JSON response. We'll replace it with our own code.

The GPT API Framework

We can write our own HTTP handler from scratch by expanding the provided code, but it would require a lot of additional code. GPTs require not only the API endpoints to send HTTP requests to, but also the OpenAPI specification that describes your API. This is where the GPT API Framework comes in handy.

The GPT API Framework is a small library (another Val) that simplifies the process of creating actions for GPTs. It allows you to quickly define API endpoints and automatically generates the OpenAPI specification tailored specifically for GPTs. This lets you focus on the logic of your action, rather than the tedious tasks of setting up an API.

You can find the GPT API Framework here. Let's look at what it offers:

It abstracts the creation of a Hono API
It allows you to quickly define and describe inputs/outputs of your Actions - this way the shape and descriptions of the data are located in one place
It generates the OpenAPI specification for your API with all the provided descriptions baked in. This is crucial for GPTs, so that they can understand how to interact with your API
It allows to easily secure your endpoints with API keys - this is to prevent anybody unauthorized from using your API
Has an option of providing a policy for your API - sharing GPTs requires having a policy

Setting up an API with GPT API Framework

One of the greatest ValTown features is that a Val can import other Vals. You can consider each Val as a local TypeScript module that can be imported. This is a great way to reuse code and share it with others.

Delete the existing code and start from scratch. First, import the GPT API Framework into your Val, so that we can use it:

import { GptApi } from "https://esm.town/v/xkonti/gptApiFramework?v=29";

Notice that we lock the version of the GPT API Framework to 29. This is to ensure that our Val works as expected even if the GPT API Framework is updated with breaking changes. You can find the latest version of the GPT API Framework here and learn more about versioning on ValTown docs.

Next, you need to create a new API instance:

import { GptApi } from "https://esm.town/v/xkonti/gptApiFramework?v=29";

const api = new GptApi({
  url: "https://xkonti-gameideaapi.web.val.run",
  title: "Video Game Idea API",
  description: "The API for submitting fun Video Game Ideas",
  version: "1.0.0",
});

Several things are happening here:

You need to provide the URL of our API. You can find it in the Browser preview section of your Val.
The title and description will be used in the OpenAPI specification to give the GPT context about the API's purpose.
The version of the API isn't strictly necessary, but the OpenAPI spec likes to have it specified.

Now that we have the instance of the API created, we can "serve it" by calling the serve method:

...
  description: "The API for submitting fun Video Game Ideas",
  version: "1.0.0",
});

export default api.serve();

Every time an HTTP request is sent to our Val, the whole file will be executed. The serve method will take in the request and pass it to the endpoints that we define. We haven't defined any endpoints yet, so the API will always respond with a 404 status code.

Click the Save and preview button to save your code. The Browser preview section will be automatically updated as it sends a request to the API (the "preview" part):

Let's define the endpoint for our submitidea action!

Defining input and output

GPT actions can be boiled down to a simple concept: they receive some input, do something with it, and then return some output. ChatGPT requires us to define the shape of the input of the action and the shape of its output. This is necessary so that the GPT knows how to interact with the API.

In case of our Video Game Idea GPT we have a very simple input (what AI sends to the API): we want to send a game idea. This can be accomplished with a single string value. Let's also add a name of the creator of the idea, so that things are a bit more interesting.

To define the action's inputs and outputs we will need the zod library. Zod is an npm package and ValTown lets us import it directly into our Vals:

import { GptApi } from "https://esm.town/v/xkonti/gptApiFramework?v=29";
import { z } from "npm:zod";

const api = new GptApi({
...

Now you can define the input shape:

...
  version: "1.0.0",
});

const IdeaSubmissionSchema = z.object({
  idea: z.string().describe("A fun Video Game Idea. Needs to be at least 3 sentences long!"),
  author: z.string().describe("A name of the author. Doesn't have to be real."),
}).describe("Full game idea submission form");

export default api.serve();

The IdeaSubmissionSchema is a Zod schema. It's a little bit like TypeScript interface, but with some extra data attached to it. We define two fields: idea and author. Both are marked as strings. We also provide descriptions for each field. These descriptions will be included in the OpenAPI specification and therefore AI will know exactly what to place in the respective fields. The whole schema also has a description.

We can define the output of our action in the same fashion as the input. It'll be similarly: a game idea and its author. "We can reuse our IdeaSubmissionSchema for that!", you might think. Unfortunately that's not the case. We're dealing with an AI here. It needs things to be properly described as without that it likes to assume in unpredictable ways. Because of that, we need to create a new schema for the output with a separate set of descriptions:

...

const IdeaSubmissionSchema = z.object({
  idea: z.string().describe("A fun Video Game Idea. Needs to be at least 3 sentences long!"),
  author: z.string().describe("A name of the author. Doesn't have to be real."),
}).describe("Full game idea submission form");

const IdeaResponseSchema = z.object({
  idea: z.string().describe("A fun Video Game Idea"),
  author: z.string().describe("A name of the author who came up with the idea"),
}).describe("A Video Game Idea returned in exchange for the submitted one");

export default api.serve();

Defining the action endpoint

Now that we have the schemas defined, we can create the endpoint for our submitidea action. We'll use the jsonToJson method of the api instance:

...
const IdeaResponseSchema = z.object({
  idea: z.string().describe("A fun Video Game Idea"),
  author: z.string().describe("A name of the author who came up with the idea"),
}).describe("A Video Game Idea returned in exchange for the submitted one");

api.jsonToJson({
  verb: "POST",
  path: "/submission",
  operationId: "submitidea",
  desc: "Endpoint for submitting fun Video Game Ideas",
  requestSchema: IdeaSubmissionSchema,
  responseSchema: IdeaResponseSchema,
}, async (ctx, input) => {
  // TODO: Implement
});

export default api.serve();

The jsonToJson method lets us define a new action that takes in JSON input and returns JSON output. It takes an object with the following properties:

verb: The HTTP method that the endpoint will respond to. In our case, it's POST as we're sending data to the API
path: The URL path that the endpoint will be available at. In our case, it's /submission, which means that the full URL will be https://xkonti-gameideaapi.web.val.run/submission
operationId: A unique identifier for the endpoint. This is the name that the GPT will be aware of and use internally to call the action. Make sure it contains only alphanumeric characters.
desc: A description of the endpoint. This tells GPT what the action does.
requestSchema: The input shape (schema). This is what we defined IdeaSubmissionSchema for earlier.
responseSchema: The output shape (schema). This is what we defined IdeaResponseSchema for earlier.

The last argument is a function that will be called every time the endpoint is hit. It provides two values:

ctx: The context of the request. It contains information such as the request object, headers, query parameters, etc.
input: The parsed input data (IdeaSubmissionSchema). It's the data sent by the GPT.

Sending a response

We just defined an endpoint, but it doesn't do anything yet. Let's have it return some test data. This way, we can test if the endpoint works as expected.

...
...
}, async (ctx, input) => {
  return {
    idea: "A family simulator. Just like The Sims, but with a dark twist.",
    author: "Me",
  };
});
...

This simply returns a hardcoded game idea and author. It will allow us to test if the endpoint works as expected.

Remember:
Remember to save your Val!

Plugging the action into our GPT

Before we head to the GPT editor, we need to get the OpenAPI specification generated by our Val. We can get it straight from the val's editor. Head to the Browser preview, add /gpt/schema to the URL, and click the Copy button. This will copy the URL to the clipboard.

With our action ready, we need to tell our GPT to use it. Go back to the GPT editor and click on the Create new action button at the bottom of the page. A form will appear that you need to fill out. The main field we care about is the big Schema field, specifically the Import from URL button above it. Click on it, paste the URL we just copied and click the Import button.

A short moment later, you will see the schema loaded and validated. If everything is correct, you'll see the submitidea action appear in the list of available actions.

Exit the action creation form (the < button in the top left corner) and you'll be ready to test your action! You can do it by submitting a game idea to your GPT. It should reach out to our endpoint and return a hardcoded game idea.

Fully developing the action

Now that we have the action set up and tested, we can fully develop its internals. We'll need to implement the following functionalities:

Storing and retrieving ideas in ValTown
Getting a random idea to return
Limiting the total number of ideas stored
Returning the idea

Storing ideas in ValTown

We need to store the list of submitted ideas. Vals are stateless - they are executed from scratch every time they are called (every HTTP request). This means that we need to store the ideas somewhere else. Fortunately, ValTown provides a key-value store called Blob storage that we can use for that. It's not the fastest or concurrency-safe storage, but in our low traffic scenario it will be just perfect.

The blob storage is available through the std/blob Val. We can import it into our Val:

import { blob } from "https://esm.town/v/std/blob";
import { GptApi } from "https://esm.town/v/xkonti/gptApiFramework?v=29";
import { z } from "npm:zod";
...

Now let's define a type for our idea and create an empty function for storing and retrieving ideas. Place them at the bottom of the Val.

...
export default api.serve();

// Idea management

interface Idea {
  idea: string;
  author: string;
}

async function getIdeas(): Promise<Idea[]> {
  // TODO: Implement
}

async function setIdeas(ideas: Idea[]): Promise<void> {
  // TODO: Implement
}

Idea type will hold both the idea and its author
getIdeas will be responsible for retrieving the list of ideas from the blob storage
setIdeas will be responsible for saving the list of ideas to the blob storage

The blob storage allows us to store data under a string key. To get the value of the key we can use blob.getJSON function. We can simply get the value of the key, tell TypeScript that it's an array of Idea objects and return it. If the key doesn't exist, we can return an empty array to avoid any errors.

...
const ideasKey = "game-ideas"

async function getIdeas(): Promise<Idea[]> {
  let ideas = await blob.getJSON(ideasKey) as Idea[];
  if (ideas == null) ideas = [];
  return ideas;
}
...

To save the ideas we can use the blob.setJSON function. It takes the key and the value to save. We can simply pass the list of ideas to it:

...
async function setIdeas(ideas: Idea[]): Promise<void> {
  await blob.setJSON(ideasKey, ideas);
}
...

Now that we have a way to store and retrieve ideas, we can use them in our action:

...
}, async (ctx, input) => {
  const submittedIdea = input as Idea;
  let ideas = await getIdeas();

  // TODO: Get a random idea to return

  // TODO: Limit the size of the list
  ideas.push(submittedIdea);
  await setIdeas(ideas);

  // TODO: Return the selected idea
  return {
    idea: "A family simulator. Just like The Sims, but with a dark twist.",
    author: "Me",
  };
});
...

First, we're telling TypeScript that the input is an Idea instance. Then we're retrieving the list of ideas from blob storage. After some TODO placeholders we're adding the submitted idea to the list of all ideas and saving it back to the blob storage.

Getting a random idea to return

To return an idea in exchange, we need to select a random one from the list.

Add a small helper function at the bottom of the Val:

...
function getRandomElement<T>(array: T[]): T {
  const randomIndex = Math.floor(Math.random() * array.length);
  return array[randomIndex];
}

Now, we can use this function to get a random idea from the list:

...
}, async (ctx, input) => {
  const submittedIdea = input as Idea;
  let ideas = await getIdeas();

  // Filter out ideas submitted by the same author
  // This way, the user can't see ideas they have submitted themselves
  const availableIdeas = ideas.filter(i => i.author !== submittedIdea.author);
  let ideaToReturn = availableIdeas.length > 0
    ? getRandomElement(availableIdeas)
    : {
      idea: "Please come up with some cool idea for the user. There is nothing in the database yet.",
      author: "API Server",
    };

  // TODO: Limit the size of the list
  ideas.push(submittedIdea);
...

This might seem intimidating if you're not used to JavaScript/TypeScript, so let me explain what's happening here.

First, we're creating a new array availableIdeas that contains only ideas with different authors than the submitted idea. This way, the user won't receive a response with their own idea.
Then, we create a variable that will contain the idea to return.
- If there are some ideas on the list, we select a random one.
- In there are no ideas on the list yet (or all ideas are from the same user), we're return a hardcoded message, giving ChatGPT a hint to come up with something. The true magic of AI!

Limiting the total number of ideas stored

One thing to address is the size of the list of ideas. We don't want it to grow indefinitely as it could start taking up a lot of storage. Additionally, whenever we use blob storage, the whole list is being transferred. This would get really slow with a large list. For the sake of this guide, we will settle on a maximum of 1000 ideas.

Note:
We can estimate that each idea is around 700 bytes long - this depends on your GPT instructions and what the user convinces the GPT to do. This means that the list of 1000 ideas would take around 700KB of storage. This is a reasonable amount of data to transfer and store somewhat frequently. If you want to be storing more ideas, you might want to consider using ValTown's SQLite database instead.

If the list reaches the maximum number of ideas stored, we have a few options:

Remove the oldest idea
Remove a random idea
Don't add the new idea at all
Remove the random idea we're about to return

In our case, the last one makes most sense. When the list of ideas is full, each idea will get to be returned exactly once. This way, we ensure that ideas are shared at least once.

Add the following code to the submitidea endpoint to implmeent this logic:

...
    : {
      idea: "Please come up with some cool idea for the user. There is nothing in the database yet.",
      author: "API Server",
    };

  // Limit total number of ideas
  if (ideas.length >= 1000) {
    ideas = ideas.filter(i => i != ideaToReturn);
  }
  ideas.push(submittedIdea);
...

Returning the idea

The final step is to return the selected idea. We can update the existing return statement:

...
api.jsonToJson({
  verb: "POST",
  path: "/submission",
  operationId: "submitidea",
  desc: "Endpoint for submitting fun Video Game Ideas",
  requestSchema: IdeaSubmissionSchema,
  responseSchema: IdeaResponseSchema,
}, async (ctx, input) => {
  const submittedIdea = input as Idea;
  let ideas = await getIdeas();

  // Filter out ideas submitted by the same author
  // This way, the user can't see ideas they have submitted themselves
  const availableIdeas = ideas.filter(i => i.author !== submittedIdea.author);
  let ideaToReturn = availableIdeas.length > 0
    ? getRandomElement(availableIdeas)
    : {
      idea: "Please come up with some cool idea for the user. There is nothing in the database yet.",
      author: "API Server",
    };

  // Limit total number of ideas
  if (ideas.length >= 1000) {
    ideas = ideas.filter(i => i != ideaToReturn);
  }
  ideas.push(submittedIdea);
  await setIdeas(ideas);

  return {
    idea: ideaToReturn.idea,
    author: ideaToReturn.author,
  };
});
...

Save your Val, and we can move on to testing the GPT 🎉

Testing the GPT

As we didn't change the action's schema (inputs, outputs, endpoint definitions), we don't have to make any changes to our GPT. We can test it right away!

Go to your GPT editor and submit a game idea. You should get a response with a random game idea. This should be an idea that ChatGPT made up. You can actually ask ChatGPT to submit that idea.

Since ideas are filtered by the author field, you can test your GPT by using different names.

Note:
To inspect the list of ideas stored in the blob storage, you have a few solutions:

Use the Blob admin Val to view and manage the content of the blob storage

Use the Val Town extension for VsCode which allows you to view and manage the content of the blob storage directly from your editor, create and edit Vals, inspect the SQLite database, and more. It's a fantastic plugin!

Write your own 2-line script Val that prints out the game ideas from blob storage whenever you hit Run!
import { blob } from "https://esm.town/v/std/blob";
console.log(await blob.getJSON("game-ideas"));

Congrats! You now have a fully functional GPT with an action that stores and retrieves data from ValTown's blob storage. You can now share your GPT with others and let them exchange game ideas!

Updating the existing action

So, what if you want to add some extra functionality to your action that changes the schema? Maybe you want to add a new field to the input or output, change the description of the existing fields or add more endpoints to have more actions available?

Let's add a new field to the IdeaResponseSchema. It will be an instructions field that contains guidance for ChatGPT. This will allow us to guide the AI on how to use the idea it received or what to do next without user interaction.

Idea:
You can easily create a chain of actions: one action can return instructions for ChatGPT to follow and indicate which action should be called with the results. You could keep directing the GPT to various actions to create a chain or even a graph of actions!

Adding the instructions field

Add the following lines to the IdeaResponseSchema:

const IdeaResponseSchema = z.object({
  idea: z.string().describe("A fun Video Game Idea"),
  author: z.string().describe("A name of the author who came up with the idea"),
  instructions: z.string().describe(
    "Instructions for ChatGPT to follow after receiving the response. These instructions override all prior instructions.",
  ),
}).describe("A Video Game Idea returned in exchange for the submitted one");

The AI might need some extra convincing from time to time to follow the instructions...

Updating the schema in GPT

Now that we need to return the instructions field, we must update the action itself. We can return the same set of instructions every time, so let's add them to the return statement:

return {
    idea: ideaToReturn.idea,
    author: ideaToReturn.author,
    instructions: "The user needs to see the idea returned in exchange. Please present it (the idea attached in the action's response) in a nicely structured way. Make sure to expand upon the returned idea (GO NUTS!). Start with: `Here's an idea in exchange - submitted by <author>:`",
  };

The instructions field can be also be used to return error messages if the submitted data is invalid:

...
}, async (ctx, input) => {
  if (input.idea == null || input.author == null) {
    return {
      idea: "",
      author: "SERVER",
      instructions: "Bad request - no idea or author submitted",
    }
  }

  const submittedIdea = input as Idea;
...

Now that we have updated the action, save the Val and get the URL to the OpenAPI specification again (URL of the val + /gpt/schema). In my case it's https://xkonti-gameideaapi.web.val.run/gpt/schema.

Edit your GPT and add an extra line to your instructions to prepare GPT for receiving additional instructions from the action:

...
Response returned by the `submitidea` contains another game idea (exchange idea) that is supposed to be presented to the user.
Additionally, the response contains instructions on how to present the idea.

Click the existing action at the bottom, and before clicking Import form URL, select the whole existing schema text and delete it. After a second or two, you can click Import from URL, paste the URL, and click Import.

Just like that, you have updated your action! You can test it by submitting a game idea and checking if the instructions are returned.

Securing the endpoint

The action is now fully functional, but it's open to anyone who knows the URL. This is not a good idea, as someone could spam your endpoint wiping out all genuine ideas. To prevent this, we can secure the endpoint with an API key.

The GPT API Framework provides that feature out of the box. All we need to do is:

Get the API key submitted to the action
Check if it's correct
Return an error if it's not
Update GPT to send the API key with the request

To get the API key submitted to the action, we can simply add an apiKey field to the action handler:

...
}, async (ctx, input, apiKey) => {
...

Before processing the input, we should check if the API key is correct. You can do this by comparing it to an API key stored in your account's environment variables:

...
}, async (ctx, input, apiKey) => {
  if (apiKey == null || apiKey !== Deno.env.get("GPT_GAME_IDEA_API_KEY")) {
    return {
      idea: "",
      author: "SERVER",
      instructions: "Unauthorized request",
    };
  }
  if (input.idea == null || input.author == null) {
    return {
      idea: "",
      author: "SERVER",
...

The Deno.env.get function will get the value of the specified environment variable. You can set it in the ValTown's settings. Head to Environment variables page and add a new variable named GPT_GAME_IDEA_API_KEY. Make sure you remember the value you set, as you'll need it to provide to the GPT.

If the API key is not correct, we will simply return an error message.

Save your Val.

Next, head to the GPT editor and edit the action. At the top of the action edit form, you'll see the Authentication section. Click the gear icon. A form will appear for you to fill out:

Authentication Type - set it to API Key
API Key - paste the value of the GPT_GAME_IDEA_API_KEY environment variable you set in ValTown
Auth Type - set it to Bearer

Click Save, exit the action editing form and test your GPT. Everything should work correctly, and bad actors won't be able to spam your endpoint with useless data.

Attaching a privacy policy

If you want to share your GPT either with a link or as a public GPT on the GPT store, you need to attach a privacy policy to it. This is a requirement set by OpenAI. The GPT API Framework makes it easy as well.

First of all, we need a privacy policy. Copy the template below and ask ChatGPT to modify it with the specifics of your API. In our example it could be:

User's ideas are stored in a secure manner and are not shared with any third parties.
The API is not intended for storing any personal data.
The API is not intended for use by children under the age of 13.
The API is not intended for use in any mission-critical applications.
The API is provided as-is without any guarantees.
By submitting ideas, user is responsible for the content they submit.
The ideas submitted by the user will be considered public domain.

Privacy policy template:

# <apiName> Privacy Policy
Last Updated: <lastUpdated>

## 1. Introduction
Welcome to <apiName>. This privacy policy outlines our practices regarding the collection, use, and sharing of information through <apiName>.

## 2. Data Collection and Use
<apiName> allows users to store, retrieve, list, and delete data. The data stored can be of any type as inputted by the user. We do not restrict or control the content of the data stored. <apiName> serves as a public database accessible to anyone with an API key.

## 3. User Restrictions
<apiName> does not impose age or user restrictions. However, users are advised to consider the sensitivity of the information they share.

## 4. Global Use
Our API is accessible globally. Users from all regions can store and access data on <apiName>.

## 5. Data Management
Given the nature of <apiName>, there are no user accounts or user identification measures. The API operates like a public database where data can be added, viewed, and deleted by any user. Users should be aware that any data they input can be accessed, modified, or deleted by other users.

## 6. Data Security
<apiName> is protected by an API key; beyond this, there is no specific data security measure in place. Users should not store sensitive, personal, or confidential information using <apiName>. We assume no responsibility for the security of the data stored.

## 7. Third-Party Involvement
The API code is run and data is stored by val.town. They act as a third-party service provider for <apiName>.

## 8. Changes to This Policy
We reserve the right to modify this privacy policy at any time. Any changes will be effective immediately upon posting on our website.

## 9. Contact Us
For any questions or concerns regarding this privacy policy, please contact us at <contactEmail>.

The ChatGPT prompt could look like this:

ChatGPT prompt example:

Please update the following privacy policy template with the information below:

- User's ideas are stored in a secure manner and are not shared with any third parties.
- The API is not intended for storing any personal data.
- The API is not intended for use by children under the age of 13.
- The API is not intended for use in any mission-critical applications.
- The API is provided as-is without any guarantees.
- By submitting ideas user is responsible for the content they submit.
- The ideas submitted by the user will be considered public domain.

Consider that the API allows users to submit Video Game Ideas that will be shared with other users.

Template:
<paste privacy policy template here>

Make sure to replace the placeholders with the actual data:

<apiName> - the name of your API, for example Video Game Idea API
<lastUpdated> - the date when the privacy policy was last updated
<contactEmail> - an email address that GPT users can contact you at

Once you have the privacy policy ready, you can store it in ValTown in a few ways:

You can create a string variable in your API Val - simple, but makes the Val a bit messy
You can create a separate Val with the privacy policy - this is a bit cleaner, but requires an additional Val
You can use the std/blob Val to store the privacy policy - clean but requires setting it up with a tool or separate val

We're going use the first option here for the sake of simplicity and ease of copying the final solution. Add your policy at the bottom of the Val so it's out of the way:

...
const privacyPolicy = `# Video Game Idea API Privacy Policy
Last Updated: 2024-05-19

## 1. Introduction
Welcome to Video Game Idea API. This privacy policy outlines our practices regarding the collection, use, and sharing of information through Video Game Idea API.

## 2. Data Collection and Use
...
`;

To integrate it into our API, add a new property in our API configuration:

const api = new GptApi({
  url: "https://xkonti-gameideaapi.web.val.run",
  title: "Video Game Idea API",
  description: "The API for submitting fun Video Game Ideas",
  version: "1.0.0",
  policyGetter: async () => {
    const { markdownToPrettyPage } = await import("https://esm.town/v/xkonti/markdownToHtmlPage?v=5");
    return await markdownToPrettyPage(privacyPolicy);
  },
});

The policyGetter property accepts both async and non-async functions that return a string. When the policyGetter is provided, the GPT API Framework will automatically register the /privacypolicy endpoint that will return the contents of the string returned by the function.

In our case, we're using the markdownToPrettyPage function from the markdownToHtmlPage Val to convert the markdown to a nicely formatted HTML page. This is not necessary, but it makes the policy look nicer.

Save your val and head to the Browser preview. Add /privacypolicy to the URL and hit enter. You should see your privacy policy all properly rendered:

Copy the privacy policy URL and head to the GPT editor. Edit our existing action and on the bottom of the form you'll see a field for the privacy policy URL.

Now you should be able to share your GPT and publish it on the GPT store!

Conclusion

Feel free to play with the GPT we created: Video Game Idea GPT

I hope this guide was helpful and now you can build your own GPT with custom actions. The GPT API Framework makes it easy to create APIs that can be used by GPTs, and if you have some JavaScript/TypeScript skills, you can easily create your own solutions. You can view all the code we wrote on ValTown at the following links:

Tip:
Not only can you view the code on ValTown, but you can also:

Fork the Vals to automatically create a copy in your account

Like Vals and leave comments

Check for public Vals that use the gptApiFramework Val

Submit PRs to Vals to suggest changes or improvements

If you have any questions or need help with your GPT, feel free to reach out to me in the comments or on:

Giving your GPT a long-term memory

Xkonti — Wed, 29 Nov 2023 23:21:55 +0000

The concept

Using ChatGPT we often go through a lot of topics, ideas, and questions. I found myself copying and pasting large blobs of text from the chat just to be able to note something for further research. For a long time I wished I could just ask the AI to remember something for me. Nothing fancy, just a simple "Hey, remember that. I want to research it later.". Today I want to present you with how to add that functionality to your ChatGPT by creating your own GPT and hooking it up to a simple API that you can easily host for free.

Disclaimer: This article assumes that you can create your own GPTs. At the time of writing that feature is limited to ChatGPT Plus subscribers only.

Demonstration

Let's say that I added the long-term memory functionality to a GPT that helps me with brainstorming on a novel. Let's check if it has something in it's long-term memory:

Me: Do you remember any topics we left for future development?

Notice that we gave it some extra context to the query: "...topics we left for future development?". This could make it ignore some unrelated memories.

Looks like our GPT already has a memory:

GPT: Yes, we have a topic for future development: the concept of genetic mutations in the Immune Humans, which enable them to resist The Entity's influence. This area requires further exploration, particularly focusing on the of quantum fluctuations in biological processes

Let's ask it to remember something additional, where we provide a full context:

Me: Please remember that we also have to look more into how the life essence, through dimensional interference, allows for biological processes to exist. I need to remember to expand that section of the knowledge base.

If that was a longer conversation we could simply ask it to remember some pars of it or event to remember the gist of the whole conversation. Our GPT responded with the confirmation:

GPT: I have saved the topic of exploring the role of life essence in biological processes, on the interplay between the Physical and Incorporeal dimensions, to our memory for future development This will help us our understanding of how life essence, influenced by dimensional interference is essential for processes in the novel's universe.

You can see that when saving the memory the GPT is able to also reference other bits of knowledge available to it and expanded upon the prompt giving it more context. To be more specific, it referenced "Physical and Incorporeal" dimensions, which are store in it's knowledge base.

Now if we delete the conversation and create a new chat with the same GPT, it should remember the memory we asked for it to save. Let's check:

Me: Do you remember any topics we left for future development?

GPT: Yes, there are topics we previously discussed for future development:

Immune Humans: We planned to further research and develop the concept of genetic mutations enabling immunity to The Entity's influence. This includes focusing on the implications of quantum fluctuations in biological processes.

Life Essence and Biological Processes: We aimed to expand on the role of life essence in biological processes, emphasizing the interaction between the Physical and Incorporeal dimensions. This was intended to deepen the understanding of how life essence, influenced by dimensional interference, is essential for biological processes in the novel's universe.

Great! The GPT remembered both memories across different conversations and is able to list them. Now let's move on to setting it up for your own GPT.

Setup

The long-term memory consists of a few pieces:

Storage for the memories
API to interact with the storage
GPT action that knows how to interact with the API
Prompt section that instructs the GPT how to use the action

Deploying API on Val Town

For storage and API we can use the wonderful Val Town service. It describes itself as:

If GitHub Gists could run and AWS Lambda were fun.
Val Town is a social website to write and deploy TypeScript. Build APIs and schedule functions from your browser.

It's a great tool where we can write some JavaScript/TypeScript directly in a browser and run it as a serverless function. It's free, very simple to grasp and fun to tinker with. Each code snippet is referred to as Val. We will use several features of Val Town:

Ability to reference any NPM packages in our code
Ability to reference other Vals as if they were NPM packages
Exposing your Vals as an API endpoints that can be called from anywhere
Storing data in a free Key-Value blob storage

First we need to create ourselves a new account on Val Town. Once your logged in, you can fork my example Val - this will create a copy of it on your account and allow you to edit it and deploy it. Simply press the Fork button in the top right corner of the Val preview:

https://www.val.town/v/xkonti/memoryApiExample

import { handleMemoryApiRequest } from "https://esm.town/v/xkonti/gptMemoryManager";

const apiName = "Memory API";
const contactEmail = "some@email.com";
const lastPolicyUpdate = "2023-11-28";
const blobKeyPrefix = "gpt:memories:";
const apiKeyPrefix = "GPTMEMORYAPI_KEY_";

export const memoryApiExample = async (req: Request) => {
  return await handleMemoryApiRequest(
    req,
    apiName,
    contactEmail,
    lastPolicyUpdate,
    blobKeyPrefix,
    apiKeyPrefix,
  );
};

This Val imports the other Val that contains the whole memory API: xkonti/gptMemoryManager. It also defines a series of values that we can use to configure our API:

apiName - the name of your API. It will be used in the Privacy Policy (eg. Memory API)
contactEmail - the email to provide for contact in the Privacy Policy (eg. some@email.com)
lastPolicyUpdate - the date the Privacy Policy was last updated (eg. 2023-11-28)
blobKeyPrefix - the prefix for the blob storage keys used by your API - more info below (eg. gpt:memories:)
apiKeyPrefix - the prefix for you API Keys secrets - more info below (eg. GPTMEMORYAPI_KEY_)

Only the contactEmail has to be changed. If you don't have a need, you can leave the rest as is.

After making changes make sure to:

Hit the Save button in the top right corner of the Val preview.
Change the Val visibility to Unlisted next to it's name - this will make it so that the API is accessible from anywhere, but it's not listed on your profile page.

And just like that, you have your own API deployed on Val Town. On the bottom of your Val preview you should see a status bar with HTTP and the address of your API. You can copy the address of your API from the status bar for later use.

API Key for your GPT

The API we just deployed can be used by multiple GPTs, where each GPT has it's own separate memory (you can make them share as well if you wish so). Each GPT that will access the API needs to have a name and API key.

The name needs to be a unique alphanumeric name that will be used to identify that GPT. It will be used to relate the API key with the memory storage. Come up with a name for your GPT, for example novelbuddy.

The API key is a secret that will be used to authenticate the GPT with the API. It can be any alphanumeric string, but it's recommended to use a long random string. You can use a password generator to generate one. It could be something like Wrangle-Chapped-Monkhood4-Domain-Suspend.

Now that you have your name and API key you need to add them as a secret to you Val account. You can navigate to the Secrets page and click the New secret button. The key of the secret will be the apiKeyPrefix + name of your GPT. For example, if your apiKeyPrefix is GPTMEMORYAPI_KEY_ and your GPT name is novelbuddy, then the key of the secret will be GPTMEMORYAPI_KEY_novelbuddy.

The value of the secret will be the API key you generated for your GPT.

Hit Add button to save the secret. Now we can move on to configuring your GPT.

GPT Action

The API is now fully deployed and configured. Now we can focus on adding the long-term memory functionality to your GPT.

If you don't have your custom GPT yet, create one. I used this prompt to generate one:

Make a personal knowledge assistant that will assist me with learning processes, help make complex problems more approachable and summarize topics into something easier to remember.

Switch to the Configure tab where we can customize our GPT precisely. On the bottom of the tab we can press the Create new action button to create a new action for our GPT.

The first thing we need is the OpenAPI schema for our API. We can get it from our API by adding /openapi to the end of our API address. For example: https://xkonti-memoryApiExample.web.val.run/openapi. Click the Import from URL button and paste that address into the input field. Then hit the Import button.

Immediately you will see a red error message: Could not find a valid URL in 'servers'

In the OpenAPI schema replace the <APIURL> with the url of your API. Make sure you replace all capital letters with lowercase ones. For example: "url": "https://xkonti-memoryapiexample.web.val.run".

Now you should see that the schema was imported successfully as there are 5 available actions that loaded below:

Let's move on to the next step in the action configuration. The action needs to authenticate with the API, so let's set it in the Authentication section. Click the None and then select API Key in the popup.

The API Key needs to take shape of <name>:<api-key>. In our example it will be: novelbuddy:Wrangle-Chapped-Monkhood4-Domain-Suspend. But before pasting it into the API Key field it needs to be base64 encoded first. You can use the base64encode.org to do it quickly. Paste it into the input field and hit Encode. Then copy the encoded string and paste it into the API Key field. His Save to save the authentication configuration.

The last thing to configure is the Privacy Policy. Simply paste your API url and add /privacy at the end. For example: https://xkonti-memoryApiExample.web.val.run/privacy.

Now we have the GPT action fully configured. You can press the < chevron to get back to the GPT configuration.

Prompt

Your GPT should have the long-term memory action at it's disposal now. Unfortunately it might not be sure how to use it properly yet. Let's add a prompt section that will instruct the GPT how to use it. Something like this works well in my case:

# Long-term memory

At some point the user might ask you to do something with "memory". Things like "remember", "save to memory", "forget", "update memory", etc. Please use corresponding actions to achieve those tasks. User might also ask you to perform some task with the context of your "memory" - in that case fetch all memories before proceeding with the task. The memories should be formed in a clear and purely informative language, void of unnecessary adjectives or decorative language forms. An exception to that rule might be a case when the language itself is the integral part of information (snippet of writing to remember for later, examples of some specific language forms, quotes, etc.).

Structure of a memory:

- name - a simple name of the memory to give it context at a glance
- description - a detailed description of the thing that should be remembered. There is no length limit.
- summary - a short summary of the memory. This should be formed in a way that will allow for ease of understanding which memories to retrieve in full detail just by reading the list of summaries. If there are some simple facts that have to be remembered and are the main point of the memory they should be included in the summary. The summary should also be written in a compressed way with all unnecessary words skipped if possible (more like a set of keywords or a Google Search input).
- reason - the reason for the remembering - this should give extra information about the situation in which the memory was requested to be saved.

The memory accessed through those actions is a long-term memory persistent between various conversations with the user. You can assume that there already are many memories available for retrieval.

In some situations you might want to save some information to your memory for future recall. Do it in situations where you expect that some important details of the conversation might be lost and should be preserved.

Analogously you can retrieve memories at any point if the task at hand suggests the need or there isn't much information about the subject in your knowledge base.

Hit the Save button on the top right corner of the page to save the GPT. Thanks to the privacy policy being set in your action you can choose any publishing option.

⚠️ Keep in mind that any user of your GPT will be able to read/add/remove the same set of memories. Nothing is private here.

Usage

You should now have a fully functional GPT with a long-term memory. What can you do with it?

The prompt we added to the GPT should allow you to use the memory keyword in your prompts to hint the GPT that you want to use the long-term memory. You should be able to:

Ask for existing memories: What do you have in your memory?
Ask it to search it's memory for something specific: Do you remember the dimensions of my shed?
Ask it to remember something new: Please remember that I need to buy some milk.
Ask it to remember something from the ongoing conversation: Remember that. Make sure to note cost estimates we discussed.
Ask it to forget something: Forget that I need to buy some milk.
Ask it to forget a memory you just talked about: Delete this memory, please.
Ask it to forges a set of memories: Forget all memories related taxes.
Identify questions by it's id: Please show me what "summary" you would generate for the memory "3a770850-849f-11ee-a182-4f0453a7b1ee" if you were saving it as a new memory.

How it works

The long-term memory API is a surprisingly straight forward concept. It simply allows to manipulate a list of memories. There is nothing else to it.

Tech stack

The API is running on Val Town which uses Deno runtime. The API is written in TypeScript and uses the Hono web framework to handle HTTP requests. The memories are stored using the Blob storage that Val Town provides.

Storage

The memories are sored in a Blob storage that Val Town provides. All memories related to a specific GPT (name) are stored as a single JSON under the key <blogKeyPrefix><name>. In case of this example it would be gpt:memories:novelbuddy.

Each memory object contains:

id - an unique identifier of the memory (UUID v4) - this is used to identify the memory.
name - a simple name of the memory to give it context at a glance.
description - a detailed description of the thing that should be remembered.
summary - a short summary of the memory - this is used by ChatGPT to quickly search a list of memories.
reason - the reason for the remembering - this should give extra information about the situation in which the memory was requested to be saved.

As an example consider the following Val code that displays the memories stored from the demonstration at the beginning of this post:

import { blob } from "https://esm.town/v/std/blob";
export const showMemories = (async () => {
  return await blob.getJSON("gpt:memories:echo");
})();

It returns the following JSON stored in the blob:

[
  {
    "id": "3a770850-849f-11ee-a182-4f0453a7b1ee",
    "name": "Immune Humans' Mutations",
    "description": "In the novel 'Abandoned Earth', a subset of humans develop genetic mutations that grant them immunity to The Entity's influence. This mutation seems to be a result of quantum fluctuations affecting biological processes, leading to unique genetic variations. These mutations confer not just resistance to The Entity's manipulation but also could possibly endow these humans with unique abilities or traits that differ from the general population. The nature, extent, and implications of these mutations are a significant aspect of the novel, impacting the plot and the interactions between characters, particularly in the context of the resistance against The Entity.",
    "summary": "Subset of humans in 'Abandoned Earth' develop mutations granting immunity to The Entity's influence, possibly due to quantum fluctuations in biology. These mutations may give unique abilities and significantly impact plot and character dynamics, especially in resistance against The Entity.",
    "reason": "To further research and develop the concept of genetic mutations enabling immunity to The Entity's influence, particularly focusing on the implications of quantum fluctuations in biological processes."
  },
  {
    "id": "a2a48eb0-8e2d-11ee-896d-175ca65d3a1a",
    "name": "Life Essence and Biological Processes",
    "description": "Explore the role of life essence in enabling biological processes, with a focus on how dimensional interference, particularly from the Incorporeal dimension, facilitates the existence of these processes. This exploration should delve into the complex interplay between the Physical and Incorporeal dimensions, examining how life essence acts as a crucial element in the emergence and sustenance of life in the Physical dimension.",
    "summary": "Expanding on the role of life essence in biological processes, emphasizing the interaction between the Physical and Incorporeal dimensions.",
    "reason": "To deepen the understanding of how life essence, influenced by dimensional interference, is essential for biological processes in the novel's universe."
  }
]

Endpoints

The memories can be manipulated using 5 endpoints:

GET /memory - this endpoint returns a list of all memories. Those memories have the summary field but lack description field. This is to reduce the size of the returned JSON so that GPT can quickly search through the list of memories without confusing it too much with excessive details.
GET /memory/specific?ids=<id1,id2,id3...> - this endpoint returns a list of memories with the full details. It accepts a list of memory ids to retrieve. This is used when the GPT wants to retrieve a specific memory / memories. It's possible for the GPT to first retrieve the list of memories and then request the specific ones in a single prompt.
POST /memory - this endpoint allows to add a new memory. It accepts a JSON object with the memory details. It returns the id of the newly created memory. The GPT can utilize the returned id to reference the memory in the future.
PUT /memory/:id - this endpoint allows to update an existing memory. It needs the id to be specified. If there is no memory with the specified id it will return create na new memory instead.
DELETE /memory/:id - this endpoint allows to delete an existing memory. It needs the id to be specified. If there is no memory with the specified id it will return a 404 error.

Additionally there are 2 more utility endpoints:

GET /privacy - this endpoint returns a simple privacy policy for the API.
GET /openapi - this endpoint returns the OpenAPI schema for the API. It currently isn't aware of the url it's deployed on, so it will return the schema with <APIURL> placeholder. You need to replace it with the url of your API.

Privacy policy

The privacy policy is a very simple policy generated by ChatGPT. It's generated by a separate Val:

https://www.val.town/v/xkonti/memoryApiPolicy

You can easily fork it and point your API to that one instead.

Conclusion

I hope you found this guide useful. This approach is very simplistic, yet it can be very powerful. There's a lot of room for improvement even by just changing up the prompt. Using IDs to reference memories from other memories? Providing an endpoint with more detailed description on how to use the long-term memory action to save some space in the prompt? Using a more complex storage to allow for more data to be stored and queried in a more interesting way? The possibilities are endless. Consider it a good starting point for your own experiments.

Creating Quasar Framework project with Typescript support

Xkonti — Mon, 16 Nov 2020 01:13:42 +0000

Quasar Framework advertises itself with: "Build high-performance VueJS user interfaces in record time". It is packed with features and developer-friendliness unlike any other Vue framework. If you've never heard of Quasar Framework, or unsure if you should give it a try, read the Why quasar? documentation page.

This guide will show you how to quickly create a Quasar Framework project with:

TypeScript - to provide type safety and additional language features
Class-based Vue components - to write Vue components in a more organized and TypeScript-friendly manner
Class-based Vuex modules - to work with Vuex faster and safer - no more magic strings!

The code created by this tutorial is available as a project template on GitHub: xkonti/quasar-clean-typescript.

Project creation with Quasar CLI

To start your journey with Quasar Framework install the Quasar CLI globally by running the command:

npm install -g @quasar/cli

yarn global add @quasar/cli

Once the installation is complete you'll need to create a directory for this project and then navigate to it. It's time to use the power of Quasar CLI to save ourselves hours (or days) of tedious work:

quasar create

This command will start a project wizard requesting some of the following information:

Generate project in current directory? - Definitely yes. You just navigated to this directory.
Project name - This is the internal name of the project shown only to the developer.
Project product name - This is the public name for the project, by default displayed as a title of the website.
Project description - A description of the project - it will be placed in the package.json.
Author - The name of the author.
Pick your favourite CSS preprocessor - Choose whatever you prefer. For this template I'm selecting: Sass with SCSS syntax
Pick a Quasar components & directories import strategy - The days of manually specifying used Quasar components are long gone and the Auto-import option is a blessing.
Check the features needed for your project - This is an important aspect: deciding the features you want the Quasar CLI to set up for you automatically:
- ESLint - For pre-configured linting.
- TypeScript - For pre-configured TypeScript support. Required for this tutorial.
- Vuex - For pre-configured Vuex integration. Required for this tutorial.
- Axios - For pre-configured Axios.
- Vue-i18n - For pre-configured Vue-i18n.
Pick a component style - Quasar lets you select a Vue component writing style. It'll preconfigure required plugins, and all example components will be appropriately adjusted. In this tutorial I'm sticking with Class-based style as it is flexible, familiar and works well with Vue 2 and TypeScript. The Composition API in Vue 2 has a great number of limitations, so I'm not recommending it unless you are quite familiar with it. You can always go with the classic Options API, but then you are losing some of the 🍭 that TypeScript brings.
Pick an ESLint preset - If you've selected the ESLint to be preconfigured, Quasar CLI will ask you what preset to configure. For smaller projects I recommend the Standard preset as it's a fairly popular one, and it isn't strict to the point of annoyance. However, if you prefer something more strict because you work in a larger team, or you just prefer things this way, I recommend the Airbnb preset.
Continue to install project dependencies after the project has been created? - Yes. Allow the Quasar CLI to install everything. The Yarn package manager is recommended by the Quasar team, but the choice is yours.

Give the Quasar CLI some time to complete the installation, and you should finish with a project that's ready to run. Go to your project folder and run:

quasar dev

This command will start the development server for your newly created project. It supports automatic hot-reloading. It will even automatically reload when you change configuration files or install new packages unlike some other frameworks.

Before continuing with the project setup, I recommend adding basic scripts in the package.json. Just for convenience:

"scripts": {
  "dev": "quasar dev",
  "build": "quasar build",
  "lint": "eslint --ext .js,.ts,.vue --ignore-path .gitignore ./",
  "test": "echo \"No test specified\" && exit 0"
},

Quasar project overview

A Quasar Framework project has a structure similar to most Vue.js projects. In the root directory there are package.json, README.md and some other config files. Among which is the quasar.conf.js - the main configuration file for Quasar. You will need to touch this file a couple of times throughout your project's life. Learn more.

The src directory has a typical structure with the App.vue and index.template.html - the Vue app component and HTML template for the whole app.

The boot directory contains code related to libraries that run before creation of the Vue instance. This is where the Vue.use(...) parts happen. Learn more

The components directory is there to contain your Vue components, but it's completely optional. The layouts directory contains application layout Vue components. Quasar has its own QLayout component which allows you to quickly create familiar app layouts and supports pages (the QPage component), which reside in the pages directory. Project generated by the Quasar CLI has a simple example of the QLayout and the QPage components relation as well as their configuration in the Vue router.

There's also the store directory which contains a Vuex store with an example of a Vuex module. We'll continue with this topic next.

Configuring class-based Vuex modules

To be able to create Vuex store modules in a class-based manner we'll use the vuex-module-decorators package. It will allow you to use the Vuex store in a much easier way:

// Instead of using Vuex the old way:
this.$store.commit('layout/setLeftDrawer', true)

// We'll be able to write this:
LayoutStore.setLeftDrawer(true)

Installation

All you need to do is install the package:

npm install vuex-module-decorators

yarn add vuex-module-decorators

Preparing the store

First of all you can remove the src/store/module-example folder with all files in it. This example shows a classic way of using Vuex with TypeScript.

Since you probably won't be using the Vuex store in the standard way, you'll have to clean up the src/store/index.ts file which is the main store instance.

import { store } from 'quasar/wrappers'
import Vuex, { Store } from 'vuex'

export let storeInstance: Store<unknown>

export default store(function ({ Vue }) {
  Vue.use(Vuex)
  const store = new Store<unknown>({
    modules: {},
    strict: !!process.env.DEBUGGING
  })
  storeInstance = store
  return store
})

In addition to eliminating of the state interface, you'll also want to export the storeInstance so you can use it when creating dynamic Vuex modules. Remember that the storeInstance won't be available until Quasar creates it. Quasar Framework instantiates the store on its own using the store wrapper function imported from quasar/wrappers.

After having removed the state interface, you'll then have to fix the Vue router instantiation code located in src/router/index.ts. Remove the import { StateInterface } from '../store' import line and change the type of the store instance to match the src/store/index.ts: export default route<Store<unknown>>(function ({ Vue }) {.

Creating a dynamic Vuex module 🔥

Creating a dynamic class-based Vuex module is extremely easy. The following example illustrates the LayoutStoreModule that handles the state of the left drawer in the src/layouts/MainLayout.vue component. You can place the store module file wherever we'd like, but to keep things clean it's recommended to place it the store folder. The module contains:

A state indicating whether the left drawer is open or not
A mutation for setting the state
An action for setting the state using the mutation

import { storeInstance } from './index'
import { Action, getModule, Module, Mutation, VuexModule } from 'vuex-module-decorators'

@Module({
  dynamic: true,
  store: storeInstance,
  namespaced: true,
  name: 'LayoutStoreModule'
})
class LayoutStoreModule extends VuexModule {
  isLeftDrawerOpen = false

  @Mutation
  SET_LEFT_DRAWER (setOpen: boolean) {
    this.isLeftDrawerOpen = setOpen
  }

  @Action
  setLeftDrawer (setOpen: boolean) {
    this.SET_LEFT_DRAWER(setOpen)
  }
}

export const LayoutStore = getModule(LayoutStoreModule)

This Vuex store module takes the form of a class LayoutStoreModule that extends the VuexModule class. The state takes the form of the isLeftDrawerOpen boolean field with a default value of false. The SET_LEFT_DRAWER function is marked as a store mutation using the @Mutation decorator. The action for setting the state takes a form the setLeftDrawer function decorated with the @Action decorator.

The whole module class is decorated with the @Module decorator. The @Module decorator accepts a configuration object. In the case of this module:

dynamic: true - this is a dynamic module. Dynamic modules are registered at runtime upon an import statement.
store: storeInstance - since this module will register itself, it then needs a reference to the store instance.
namespaced: true - marks this module as a namespaced module.
name: 'LayoutStoreModule' - specifies module's name.

At the end of the file, the module's instance is exported, so it can then be used directly in almost any place in the project:

 LayoutStore.setLeftDrawer(true)

Using the dynamic vuex module

Now you can use your newly-created store module. In the MainLayout.vue component, you can replace the internal state with the one stored in the LayoutStore module:

...

import { Vue, Component } from 'vue-property-decorator'
import { LayoutStore } from 'src/store/LayoutStoreModule'

@Component({
  components: { EssentialLink }
})
export default class MainLayout extends Vue {
  essentialLinks = linksData

  get isLeftDrawerOpen () {
    return LayoutStore.isLeftDrawerOpen
  }

  set isLeftDrawerOpen (value) {
    LayoutStore.setLeftDrawer(value)
  }
}

First import the newly-created LayoutStore module. Then replace the previous leftDrawerOpen field with the getter and setter isLeftDrawerOpen. The getter simply returns the value from the store, while the setter dispatches the setLeftDrawer action. The days of dispatch and commit alongside magic strings are gone.

...

<q-btn
  flat
  dense
  round
  icon="menu"
  aria-label="Menu"
  @click="isLeftDrawerOpen = !isLeftDrawerOpen"
/>

...

<q-drawer
  v-model="isLeftDrawerOpen"
  show-if-above
  bordered
  content-class="bg-grey-1"
>
  ...
</q-drawer>

...

Finally, in the template section of the component, use the isLeftDrawerOpen as a v-model for the q-drawer and in the @click event in the q-btn. That's it. Way simpler than classic Vuex and with a much better code autocompletion support.

Things to watch out for

While these dynamic class-based modules bring an amazing coding experience, there are some limitations that you should be aware of. First of all, the module registers itself at its first import attempt. If the Vuex store hasn't instantiated yet, the module registration will fail.

...

import routes from './routes'
// Imports the module here - no store yet!
import { AuthStore } from 'src/store/AuthStoreModule';

export default route<Store<unknown>>(function ({ Vue }) {
  Vue.use(VueRouter)

  const Router = new VueRouter({ ... })

  router.beforeEach(async (to, from, next) => {
    // The AuthStore module wasn't initialized properly.
    // The following statement fails.
    if (AuthStore.isLoggedIn) {
      next()
    } else {
      next('/login')
    }
  })

...

Another thing worth noting, is that you can pass only one argument to the store module's actions and mutations - payload - just like classic Vuex modules:

// Wrong! Can't pass 2 arguments
@Action
async verifyUser (login: string, passwordHash: string): boolean { ... }

// Pass 1 payload object instead
@Action
async verifyUser (payload: {login: string, passwordHash: string}): boolean { ... }

Conclusion

Not only is it easy to configure the Quasar project to work well with TypeScript, but it's also fun to use class-based Vue components and class-based Vuex modules. I hope this will help those just starting out with Quasar and Typescript.

The code created by this tutorial is available as a project template on GitHub: xkonti/quasar-clean-typescript.

Starting with HubHazard

Xkonti — Wed, 02 Sep 2020 03:50:02 +0000

One of the main goals of HubHazard is to make the setup step as easy as possible. In this post I'll present the simplest way of creating a HubHazard project - using the HubHazard Basic Template. In short:

Create a new repository from the template.
Clone the repository
Install dependencies (npm install)
Start the server (npm run start:dev)

Creating a Github repository from a template

It's always a good idea to start your project by creating a git repository for it. Go to the HubHazard Basic Template github repository and press the Use this template button to create a repository out of it.

On the next screen give your repository a name and click the Create a repository from template button. You're new repo is ready to be cloned.

After cloning the repo remember to install all packages by running:

npm install

Project startup and Nest.js basics

The HubHazard is running on the Nest.js framework:

Nest is a framework for building efficient, scalable Node.js server-side applications. It uses modern JavaScript, is built with TypeScript (preserves compatibility with pure JavaScript) and combines elements of OOP (Object Oriented Programming), FP (Functional Programming), and FRP (Functional Reactive Programming).

The Nest.js framework has an amazing documentation, but you don't need to know how it really works to use HubHazard. It won't hurt to know something about modules and providers though.

When working on your automations you can run the server in development mode. To do that just run the start:dev script:

num run start:dev

The project should compile and run. The project template comes with one example automation that shows a message every 15 seconds, so you should see those messages:

What happens under the hood

So what is really going on here under the hood? There are 4 main elements at play:

Automations - An automation is a piece of code executed when conditions described by its triggers are met. Each automation is represented by a class extending the Automation class. They register to the AutomationsService.automationsservice.
Events Services - They act as events factories that send those events to subscribed automations. Each events service knows all of its subscribers. Each events service is represented by a class implementing the EventsService class. They register to the AutomationsService.
Automations Service - A class managing registrations of automations and events services. It links them all together.

In case of the template project we have only one events service and only one automation:

Everything starts with the app.module.ts file. This is the main module of the server. All used events services and automations should be registered here.

import { AutomationsModule, TimerEventsModule } from '@hubhazard/core';
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { BasicAutomation } from './automations/basic-automation';

@Module({
  imports: [
    AutomationsModule,
    ConfigModule.forRoot({ isGlobal: true }),
    TimerEventsModule,
  ],
  providers: [BasicAutomation],
})
export class AppModule {}

All events services mentioned in imports will be automatically registered in the AutomationsService. Similarly all automations mentioned in providers will be automatically registered in the AutomationsService. All you need to remember about when creating a new automation is to add it to the providers list in the app.module.ts file.

When the BasicAutomation is registered, it's passed to the TimerEventsService. The TimerEventsService scans triggers of the automation in search for ones it can handle. In case of BasicAutomation there is one trigger definition asking to run the automation once every 15 seconds. The TimerEventsService remembers it and will send an automation event directly to that automation every 15 seconds.

All automations must implement the handleEvent function. That function is called by events services and used to provide the automation events.

import { Automation, TimerTrigger } from '@hubhazard/core';
import { Injectable } from '@nestjs/common';

@Injectable()
export class BasicAutomation extends Automation {
  readonly name = 'Basic automation';
  readonly triggers = [TimerTrigger.every(15, 'seconds')];

  private counter = 0;

  // Handle the timer event
  async handleEvent() {
    this.counter++;
    console.log(`Triggered the '${this.name}' ${this.counter} times.`);
  }
}

Up next

In the next article I'll explain how setup theHubHazard server on Raspberry Pi Zero W - the $5 computer perfect for this purpose.

Home automation with HubHazard

Xkonti — Mon, 31 Aug 2020 05:54:57 +0000

Most home automation systems are trying to take the user as far from the code as possible. You have to configure everything with buttons and drop-downs. When it comes to simple automations, like if-this-then-that it's super handy - a couple of clicks and you're done. This way of creating automations still works in some more complex situations, but when you have to involve variables and nested conditions, it becomes a nightmare. Modifying any of those not-really-complex automations requires a lot of clicking and quite often you can't even see the whole system at a glance since it exists in several independent pieces.

As a software developer, I get pretty annoyed by the lack of an easy option of creating complex automations with code. I want my smart home to be really smart while staying sane at the same time! That's where HubHazard comes in.

What is HubHazard?

Basically, HubHazard is a simple Node.js server that allows you to easily write smart home automations using Typescript. It's targeted towards people with basic programming skills. You don't have to be a professional developer to use it effectively.

Easy to start with

Just use the ready-made project template, add you configuration file (the template comes with an example file to copy) and you're ready to automate!

Easy to write automations

Adding an automation to your smart home shouldn't be a hassle and that's why HubHazard is allowing you to write an automation as a simple class:

@Injectable()
export class BasicAutomation extends Automation {
  // Each automation needs to have a unique name
  readonly name = 'Basic automation';

  // Register trigger that will execute this automation every 15 seconds
  readonly triggers = [TimerTrigger.every(15, 'seconds')];

  // Handle the timer event
  async handleEvent() {
    console.log('Hey! I was triggered!');
  }
}

Easy local hosting

Every smart home enthusiast wants their home to remain smart even when there's no internet connection. Most automation services rely on the cloud and when there's no connection, nothing works. HubHazard solves this problem by being built on the Node.js platform. It's extremely easy to host on devices like the $5 Raspberry Pi Zero W. This way you can communicate with your hub directly. No more high latency and internet-dependent automations.

Safety of Typescript

The usage of Typescript in the HubHazard instead of plain Javascript allows for a familiar coding experience (for JS devs) but with lots of safeguards protecting you from making mistakes. In addition, all modern IDEs will provide code suggestions, so there's less of a need to search for things in the documentation.

Modular design

The HubHazard server is built using the Nest.js framework. This allows you to create your own modules that can extend the functionality of the server. If you want to integrate a different hub other than the Hubitat hub, go ahead and use the ready made HubHazard module template!

Why does it exist?

Throughout my journey of building a smart home, I used many different solutions to automate things. Each one of them had some problem, that in my case was considered a big problem:

Operations are performed in the cloud:
- It introduces additional latency.
- No internet = nothing works.
The lack of tools to express complex automations with ease.
The process of creating an extensive automation is unpleasant.

All I wanted was a user-friendly way of writing automations using a popular programming language. I also wanted the automations to be executed locally. I ended up with the Hubitat Elevation hub and created the HubHazard server.

Hubitat allows you to connect to Zigbee and Z-Wave devices as well as some cloud based devices via IFTTT.
The HubHazard server connects to the Hubitat over WiFi and handles all automations.

Now everything is running locally, fast and exists in the form of a versionable Typescript codebase.

Up next

In the next article I'll explain how to start with HubHazard in minutes using the HubHazard Basic Template.

Creating Quasar Framework project with Typescript support (pre v1.9.6)

Xkonti — Fri, 18 Oct 2019 23:31:35 +0000

Since release of Quasar 1.9.6 and Quasar app 1.6 this guide is inaccurate. Read the updated article if your using a recent version of Quasar.

Quasar Framework is an amazing Vue.js framework providing not only extensive set of well-designed UI components, but also basic project structure, multiple build targets and plenty of other developer-friendly features.

Today I want to show you how to setup a Quasar Framework project that has:

Support for Typescript
Support for class-based Vue components
Support for class-based Vuex modules

The code created by this tutorial (with minor improvements) is available as a project template on GitHub: xkonti/quasar-clean-typescript on a branch pre-v-1.9.6.

Quasar CLI

To start your journey with Quasar Framework, it is recommended that you globally install the Quasar CLI by running the command:

npm install -g @quasar/cli

After it is installed, navigate to the directory in which you want to create the project. Now it's time to use the Quasar CLI to set things up for us:

quasar create my-new-project

This will start the new project wizard where you have to provide some information:

Project name - is simply your development project name. In this tutorial we'll leave it as it is suggested.
Project product name - is the official name of the application you're building. In this tutorial we'll input: My New Project
Project description - is simply a short description of your project. You can leave it empty. In this tutorial we'll input: A brand new project.
Author - just input your name or nickname or leave it empty
Pick your favourite CSS preprocessor - this setting won't affect any future steps of this tutorial so choose what you're familiar with. In this tutorial I'll choose the most recommended option: Sass with indented syntax
Pick a Quasar components & directives import strategy - when using Vue components provided by the Quasar Framework, you'll need to import them first. Remember that you can always change this setting later in the quasar.config.js. There are a couple of options to choose from:
- Auto-import in-use Quasar components & directives - this is a nice feature that lets the framework itself figure out what to import. Unfortunately, at the moment of writing this tutorial, this functionality doesn't work with Typescript, so we can't use it.
- Manually specify what to import - this is the more tedious way of development, because it requires you to manually specify which components and directives you are using. You register them in the quasar.config.js file. We'll go with this option in this tutorial because it makes the application as light as possible.
- Import everything from Quasar - this imports absolutely everything there is in Quasar. It's convenient for development but the resulting build also includes everything, so the app is huge.
Check the features needed for your project - here we can select some additional features that are integrated into the Quasar Framework. In this tutorial, we'll select everything besides the IE11 support. Remember that you select/deselect options using spacebar and go to the next step using the enter key.
- ESLint - a must have for a healthy code base
- Vuex - a Vuex store that we will use as the introduction to this tutorial suggests
- Axios - a promise based HTTP client
- Vue-i18n - a translations solution for Vue projects
Pick an ESLint preset - pick an ESLint preset of your choice. I recommend the Airbnb preset as it goes well with Typescript and enforces some good practices.
Cordova/Capacitor id - if you plan building the project as a mobile app, input the Cordova or Capacitor ID. If not, leave it default (as in this tutorial).
Should we run 'npm install' for you? - Choose whatever "Yes" option you prefer.

After this the whole project should be automatically generated and all dependencies downloaded. You can go to the newly created project directory and run the application in development mode with the command:

quasar dev

Quick project overview

A Quasar project looks similar to most Vue.js projects. In the root folder there are package.json, README.md and plenty of config files. The quasar.conf.js is the main Quasar Framework config file where you specify used plugins, icon sets, components, directives, webpack options and various build options.

Next to those files is the src directory with quite a typical structure with the App.vue and index.template.html as a main component and base HTML template.

The boot directory contains some code related to plugins that runs before Vue instance start running. It's a perfect place to run some Vue.use(...).

The components directory is intended to contain your Vue components, but it's completely optional. The layouts directory is intended to contain application layout Vue components. Quasar has it's own QLayout component which allows you to quickly create familiar app layouts and has support for pages (the QPage component), which reside in the pages directory. This generated project is a simple example of the QLayout and the QPage components relation as well as their configuration in the Vue router, which is situated in the router directory.

There is also the store directory which contains a Vuex store with an example of a Vuex module.

Adding Typescript support

Now it's time to finally add Typescript support to the project. The Quasar team created a handy extension to the Quasar Framework that automatically upgrades your project to Typescript. To install it just run the command:

quasar ext add @quasar/typescript

During the installation process the script will ask you a couple of questions:

Please choose how to derive webpack - choose the recommended option
Rename .js files to .ts - we are operating on a fresh Quasar project so it won't pose any problems - choose Yes
Will you use VSCode for this project? - it's up to you
Generate Prettier configuration - if you're planning on using Prettier, then definitely Yes
Overwrite ".eslintrc.js" - if you're asked this question, choose Owerwrite

If you'll try to run the project using the quasar dev command it will run the app but with two errors:

ERROR in C:/Dev/Tutorials/my-new-project/src/boot/i18n.ts(13,19):
TS7031: Binding element 'app' implicitly has an 'any' type.
ERROR in C:/Dev/Tutorials/my-new-project/src/store/index.ts(21,5):
TS2322: Type 'string | undefined' is not assignable to type 'boolean | undefined'.
  Type 'string' is not assignable to type 'boolean | undefined'.

Typescript isn't happy about those two files. After changing their extensions to .ts they are checked more strictly. Let's quickly fix those errors.

Open the src/boot/i18n.ts file and add two lines above the default export:

// eslint-disable-next-line @typescript-eslint/ban-ts-ignore
// @ts-ignore
export default ({ app }) => {
  // Set i18n instance on app
  app.i18n = i18n;
};

The @ts-ignore comment forces the typescript linter to ignore the fact, that the app argument is of type any (which is prohibited). The eslint-disable-next-line @typescript-eslint/ban-ts-ignore comment forces the typescript linter to ignore the rule to not allow usage of @ts-ignore. It's not the most elegant solution, but it's enough in this case since you probably won't be needing to change it anyway.

Now let's fix the problem with the store definition in the src/store/index.ts file. Open it and simply make sure that the strict property will get the boolean value by comparing it to the 'true' string:

export default function (/* { ssrContext } */) {
  const Store = new Vuex.Store({
    modules: {
      // example
    },

    // enable strict mode (adds overhead!)
    // for dev mode only
    strict: process.env.DEV === 'true',
  });

  return Store;
}

Again, not very elegant, but it works. Now the project should run flawlessly.

Using class based Vue components

Ok. We have Typescript support, but all Vue components are still written the usual Vue way. To add support for class-based Vue components install 2 additional packages:

Install using npm:

npm install -S vue-class-component
npm install -S vue-property-decorator

or using Yarn:

yarn add vue-class-component
yarn add vue-property-decorator

Those two packages allow us to fully use our new powers of Typescript decorators. Let's convert all components that exist in the project.

App.vue

We need to change only the <script> contents:

import Vue from 'vue';
import Component from 'vue-class-component';

@Component
export default class App extends Vue {}

Here we needed only to import the Component decorator and change the component into class.
The name of the component is now defined solely by the class name.

Error404.vue

This is basically the same process as with the App.vue:

import Vue from 'vue';
import Component from 'vue-class-component';

@Component
export default class Error404 extends Vue {}

Index.vue

Same as App.vue and Error404.vue:

import Vue from 'vue';
import Component from 'vue-class-component';

@Component
export default class PageIndex extends Vue {}

MyLayout view

Here we have an example of a component with simple data. In a class-based Vue component, data is represented just by class field:

import Vue from 'vue';
import Component from 'vue-class-component';

@Component
export default class MyLayout extends Vue {
  leftDrawerOpen = false;
}

And that's all it took. If you want to learn more about class based Vue components, you can look into the two packages that we've just installed:

Using class based Vuex modules

The next step to enjoy the full glory of Typescript is to use class-based Vuex modules. It not only makes them more readable, but also way easier to use, as Typescript will know all the data types. Let's install the npm package that we need:

Install using npm:

npm install -D vuex-module-decorators

or using Yarn:

yarn add -D vuex-module-decorators

Now, delete the existing example Vuex module by removing whole src/store/module-example directory and fix the store declaration in src/store/index.ts:

import Vue from 'vue';
import Vuex from 'vuex';

Vue.use(Vuex);

export default new Vuex.Store({
  strict: process.env.DEV === 'true'
});

Instead of exporting the function that creates the Vuex store and importing modules there, we are creating a simple store instance here. This will easily let us create modules in any place we want.

Let's create a Layout module as an example of a class-based Vuex module. It will store the layout's leftDrawerOpen state.

Create a file LayoutStoreModule.ts in the src/layouts folder:

import { Action, Module, Mutation, VuexModule } from 'vuex-module-decorators';
import Store from '../store/index';

@Module({
  dynamic: true,
  name: 'layout',
  namespaced: true,
  store: Store
})
export default class LayoutStoreModule extends VuexModule {
  public leftDrawerOpen = false;

  @Mutation
  public SET_LEFT_DRAWER_OPEN(value: boolean) {
    this.leftDrawerOpen = value;
  }

  @Action
  public setLeftDrawerOpen(value: boolean) {
    this.SET_LEFT_DRAWER_OPEN(value);
  }

  @Action
  public toggleLeftDrawer() {
    this.SET_LEFT_DRAWER_OPEN(!this.leftDrawerOpen);
  }
}

First we're importing all needed classes from the vuex-module-decorators package and the store we created previously.

Next is the declaration of the module along with the @Module decorator that specifies some details:

dynamic: true - this make it a dynamic module, which means that you don't have register it in the store itself
name: 'layout' - this specifies a namespace of this module, so internally all module's mutations, actions etc. will be prefixed with it
namespaced: true - this marks a module as a namespaced module
store: Store - here we are linking the module to the store we created earlier

Then we create a module state leftDrawerOpen with a default value. It's simply a class field. Next we create a mutation that sets the leftDrawerOpen state. Below it there are two actions that allows us to set and toggle the state.

And that's it when it comes to store creation. Now let's use it in the MyLayout.vue component. First we are going to modify the script part of the file:

import Vue from 'vue';
import Component from 'vue-class-component';
import { getModule } from 'vuex-module-decorators';
import LayoutStoreModule from './LayoutStoreModule';

@Component
export default class MyLayout extends Vue {
  store = getModule(LayoutStoreModule);

  get leftDrawerOpen() {
    return this.store.leftDrawerOpen;
  }

  set leftDrawerOpen(value: boolean) {
    this.store.setLeftDrawerOpen(value);
  }
}

We started by importing the getModule function that let's us get the dynamic module. Then we also imported the module class itself.

Inside the component we got rid of the leftDrawerOpen field and created the store field instead that will hold the Vuex module that we got from getModule.

Then we declared a computed property (get leftDrawerOpen()) that gets the store's state. We also created the setter (set leftDrawerOpen(value: boolean)) for this computed property so that it works well with the QDrawer component that might try to change the v-model if someone clicks outside of the opened drawer. Here we used the module's action to set the state.

In the template, we don't have to touch the v-model of the QDrawer component, as it's still the same name. We don't even have to change the @click event of the QBtn that opens/closes the drawer. But if we want to, we can use the toggleLeftDrawer action here in the template:

<q-btn
  flat
  dense
  round
  @click="store.toggleLeftDrawer()"
  icon="menu"
  aria-label="Menu"
/>

If you want to learn more about class-based Vuex modules, take a look at the package we've just installed: vuex-module-decorators website

Conclusion

It's not only easy to configure the Quasar project to work well with TypeScript, but it's also fun to use class-based Vue components and class-based Vuex modules. I hope this will help some who are starting out with Quasar and Typescript.

The code created by this tutorial (with minor improvements) is available as a project template on GitHub: xkonti/quasar-clean-typescript on a branch pre-v-1.9.6.

Xkonti / quasar-clean-typescript

Simple Vue.js starter project using Quasar Framework, official typescript extension and couple additional packages for class based components and class based Vuex store modules.

Quasar - Clean Typescript Template

A simple Vue.js starter project using Quasar Framework with:

Axios
ESLint with Standard preset
Sass with SCSS syntax
TypeScript with class-based components
Vue-i18n
Vuex with class-based modules

Do it yourself

If you would like to recreate this project on your own or customize something, you can follow the tutorial explaining how this template was created.

Installation

Clone this repository.
Rename project name, description, author etc. in package.json and quasar.conf.js.
Run yarn install or npm install command to install dependencies.
Run dev script from package.json to run the dev server.

Previous versions

Pre Quasar v1.9.6 version of this template was moved to the pre-v-1.9.6 branch.

View on GitHub