Forem: siegerts

Hitting Your 1 Rep Max with AI

siegerts — Tue, 03 Mar 2026 05:00:00 +0000

In the gym, your 1 rep max is the most weight you can lift for a single repetition. It's not about how many reps and sets you can do. It's about finding the absolute edge of what you're capable of. Just once, in the moment after you've warmed up or just have a day that you're "feeling it".

That's what AI gives you for thinking. Without any of the limitations.

We block ourselves. I could do this but it will take time. Or, we know the possible but are afraid to pursue because it might actually work...and then what? It will take too much time to validate, too much time to continue. So we don't start.

This isn't just for building tech. That what-if question you've had, the one that would take extreme focus and time to even try. What if you could attempt it now? And then the next one. Design a piece of furniture. Create a game. Build a business. It can translate into the physical.

This is quite honestly one of the wildest times.

I went to school for Economics. I had some sense of HTML (from MySpace pages) but I used to stall on ideas because I didn't know how to execute them. I learned to program to create. Plain and simple. I wanted to build my ideas. And that took years.

Now, that gap between having an idea and being able to act on it is almost gone. You don't need to learn a whole new skillset to start. You just need to start.

The rep ranges

If you've spent any time in a gym, you're aware of the concept of rep ranges. The number of repetitions you do with a given weight determines the type of training effect you get:

12-15+ reps: Light weight, high volume. You could do this all day. It keeps you moving but it doesn't change you.
8-12 reps: Moderate weight. This is where you build muscle. The work that makes you grow over time.
3-5 reps: Heavy weight, low reps. You're building raw capacity. Each rep demands focus.
1 rep: Your max. The most you can possibly lift. One attempt. Full effort. You find out what you're actually capable of. Sometime you fall over after 😄.

Most people spend their entire working life in the 12-15 rep range. Comfortable volume. Repeating what they already know. Answering emails. Putting together the same deck. Shipping the same type of feature. Running the same playbook. It's productive but it never tests the ceiling.

AI lets you move down the rep range without compromising risk. You can attempt the 1 rep max without the fear of failure. You can try something you never thought you could do, knowing that if it doesn't work, it's not a big deal. You can iterate quickly and learn from the attempt.

How most people use it

Right now (at least for this week because things are moving so fast) most people outside of the tech bubble use AI for the easy, repetitive stuff. Summarize this, draft that, auto-complete the thing you've done a hundred times. Nothing changes. Same work, less effort.

Some go further. They explore a domain they haven't worked in. Pick up a new tool or framework. Dig into something they've been meaning to learn. That's where I think real growth happens.

Fewer still use it to take on harder problems than they normally would. The project that felt out of reach. The decision they would have deferred to someone else.

And then there's the attempt you genuinely don't know if you can pull off. A non-technical founder building their own product. A designer prototyping something they'd normally hire a dev for. A marketer who's been outsourcing analysis learning to do it themselves. A backend developer shipping a polished UI.

Or, someone that wants to design a piece of furniture because "hey, why not?".

Most people never get past the first level. I think the unlock is realizing you can. The time cost to try is almost nothing now, especially when you would have never tried at all.

The shift

Once I got into this pattern, something changed for me. I stopped treating new ideas like R&D projects that needed justification and started just...doing them. You're not convincing yourself to "just do it" but rather accepting that you can.

A friend of mine, sales exec, told me recently "I just iterate until it looks right and does what I want it to do." That's it. No architecture planning, no analysis paralysis. Just start.

I think a lot of this is psychological. What would you do if you could hit your 1 rep max whenever you wanted? Some people embrace that. Others are paralyzed by the influx of decisions they were never faced with before. What do I build? What do I try? What's worth my time now that everything feels possible?

Work that took days, months, and sometimes years can happen in minutes. That's a lot to process.

"I could never make that"

This is the phrase I hear the most. From non-technical people who have ideas but assume the gap between idea and execution is uncrossable. From people who've been in the same role, same tools, same output for years. From technical people who've settled into the same stack, same architecture, same ceiling.

The gap was real. It's not anymore.

How I think about it

Rethinking, not outsourcing

The failure mode is obvious though. Most people get AI and immediately use it to make the easy stuff easier. Same work, less effort. That's not growth, that's automation.

I think the distinction that matters is automation vs. augmentation. Automation keeps you where you are. Augmentation pushes what you can do. Rethinking means looking at the thing you've never attempted and saying...what if I could?

To be clear, AI doesn't do it for you. It's more like having someone there who gives you the confidence to try something bigger. It's there if you fail. So you're willing to fail. Not "do this for me" but "I want to try something I've never done. Stay close."

Honestly, it's a psychological shift.

None of this works if you don't actually try though. AI doesn't generate ambition or curiosity. But if you bring those, it'll let you do more than you thought you could.

During the time that I was writing this, I also built a working mobile app with a framework (SwiftUI) that I had no experience with. I've never touched it before...

(all my opinions btw and maybe just a reflection of how I'm feeling...today)

Crawling Pages with Infinite Scroll using Scrapy and Playwright

siegerts — Thu, 08 Aug 2024 15:33:55 +0000

When crawling websites with Scrapy you'll quickly come across all sorts of scenarios that require you to get creative or interact with the page that you're trying to scrape. One of these scenarios is when you need to crawl an infinite scroll page. This type of website page loads more content as you scroll down the page like a social media feed.

There is definitely more than one way to crawl these types of pages. One way I recently approached this was to continue scrolling until the page length stopped increasing (i.e. scroll to the bottom). This post steps through this process.

This post assumes that you have a Scrapy project set up, running, and a Spider that you can modify and run.

Using Playwright with Scrapy

This integration uses the scrapy-playwright plugin to integrate Playwright for Python with Scrapy. Playwright is a headless browser automation library used to interact with web pages and extract data.

I've been using uv for Python package installation and management.

Then, I use virtual environments right from uv with:

uv venv 
source .venv/bin/activate

Install the scrapy-playwright plugin and Playwright with the following command into your virtual environment:

uv pip install scrapy-playwright

Install the browser you want to use with Playwright. For example, to install Chromium, you can run the following command:

playwright install chromium

You can also install other browsers like Firefox if needed.

Note: The below Scrapy code and Playwright integration have only been tested with Chromium.

Update the settings.py file or the custom_settings attribute in the spider to include the DOWNLOAD_HANDLERS and PLAYWRIGHT_LAUNCH_OPTIONS settings.

# settings.py
TWISTED_REACTOR = "twisted.internet.asyncioreactor.AsyncioSelectorReactor"

DOWNLOAD_HANDLERS = {
    "http": "scrapy_playwright.handler.ScrapyPlaywrightDownloadHandler",
    "https": "scrapy_playwright.handler.ScrapyPlaywrightDownloadHandler",
}

PLAYWRIGHT_LAUNCH_OPTIONS = {
    # optional for CORS issues
    "args": [
        "--disable-web-security",
        "--disable-features=IsolateOrigins,site-per-process",
    ],
    # optional for debugging
    "headless": False,
},

For PLAYWRIGHT_LAUNCH_OPTIONS you can set the headless option to False to have the browser instance open and watch the process run. This is good for debugging and building out the initial scraper.

Dealing with CORS Issues

I pass in the additional args to disable web security and isolate origins. This is useful when you are crawling sites that have CORS issues.

For example, there may be situations when required JavaScript assets are not loaded or network requests are not made because of CORS. You can isolate this faster by checking the browser console for errors if certain page actions (like clicking a button) are not working as expected but everything else is.

"PLAYWRIGHT_LAUNCH_OPTIONS": {
    "args": [
        "--disable-web-security",
        "--disable-features=IsolateOrigins,site-per-process",
    ],
    "headless": False,
}

Crawling Infinite Scroll Pages

This is an example of a spider that crawls an infinite scroll page. The spider scrolls the page by 700 pixels and waits for 750ms for the request to complete. The spider will continue to scroll until it reaches the bottom of the page indicated by the the scroll position not changing as it goes through the loop.

I'm modifying the settings in the spider itself using custom_settings to keep the settings in one place. You can also add these settings to the settings.py file.

# /<project>/spiders/infinite_scroll.py

import scrapy

from scrapy.spiders import CrawlSpider
from scrapy.selector import Selector


class InfinitePageSpider(CrawlSpider):
    """
    Spider to crawl an infinite scroll page
    """

    name = "infinite_scroll"

    allowed_domains = ["<allowed_domain>"]
    start_urls = ["<start_url>"]

    custom_settings = {
        "TWISTED_REACTOR": "twisted.internet.asyncioreactor.AsyncioSelectorReactor",
        "DOWNLOAD_HANDLERS": {
            "https": "scrapy_playwright.handler.ScrapyPlaywrightDownloadHandler",
            "http": "scrapy_playwright.handler.ScrapyPlaywrightDownloadHandler",
        },
        "PLAYWRIGHT_LAUNCH_OPTIONS": {
            "args": [
                "--disable-web-security",
                "--disable-features=IsolateOrigins,site-per-process",
            ],
            "headless": False,
        },
        "LOG_LEVEL": "INFO",
    }

    def start_requests(self):
        yield scrapy.Request(
            url=f"{self.start_urls[0]}",
            meta=dict(
                playwright=True,
                playwright_include_page=True,
            ),
            callback=self.parse,
        )


    async def parse(
        self,
        response,
    ):
        page = response.meta["playwright_page"]
        page.set_default_timeout(10000)

        await page.wait_for_timeout(5000)
            try:
                last_position = await page.evaluate("window.scrollY")

                while True:
                    # scroll by 700 while not at the bottom
                    await page.evaluate("window.scrollBy(0, 700)")
                    await page.wait_for_timeout(750) # wait for 750ms for the request to complete
                    current_position = await page.evaluate("window.scrollY")

                    if current_position == last_position:
                        print("Reached the bottom of the page.")
                        break

                    last_position = current_position

            except Exception as error:
                print(f"Error: {error}")
                pass

            print("Getting content")
            content = await page.content()

            print("Parsing content")
            selector = Selector(text=content)

            print("Extracting links")
            links = selector.xpath("//a[contains(@href, '/<link-pattern>/')]//@href").getall()

            print(f"Found {len(links)} links...")

            print("Yielding links")

            for link in links:
                yield {"link": link}

One thing that I've learned is that no two pages or sites are the same so you may need to adjust the scroll amount and wait time to account for the page and also any latency in the network round trips for the requests to complete. You can dynamically adjust this programmatically by checking the scroll position and the time it takes for the request to complete.

On the page load, I'm waiting a bit longer for the assets to load and the page to render. The Playwright page is passed to the parse callback method in the response.meta object. This is used to interact with the page and scroll the page. This is specified in the scrapy.Request arguments with the playwright=True and playwright_include_page=True options.

def start_requests(self):
    yield scrapy.Request(
        url=f"{self.start_urls[0]}",
        meta=dict(
            playwright=True,
            playwright_include_page=True,
        ),
        callback=self.parse,
    )

This spider will scroll the page with page.evaluate and the scrollBy() JavaScript method by 700 pixels and then wait for 750ms for the request to complete. Then, the Playwright page content is copied to a Scrapy selector, and extract the links from the page. The links are then yielded to the Scrapy pipeline to continue processing.

Infinite Scroll Scrapy Playwright

For situations where the page requests begin to load duplicate content, you can add a check to see if the content has already been loaded and then break out of the loop. Or, if you have an idea of the number of scroll loads, you can add a counter to break out of the loop after a certain number of scrolls plus/minus a buffer.

Infinite Scroll with an Element Click

It's also possible that the page may have an element that you can scroll to (i.e. "Load more") that will trigger the next set of content to load. You can use the page.evaluate method to scroll to the element and then click it to load the next set of content.

...

try:
    while True:
        button = page.locator('//button[contains(., "Load more")]')
        await button.wait_for()

        if not button:
            print("No 'Load more' button found.")
            break

        is_disabled = await button.is_disabled()
        if is_disabled:
            print("Button is disabled.")
            break

        await button.scroll_into_view_if_needed()
        await button.click()
        await page.wait_for_timeout(750)

except Exception as error:
    print(f"Error: {error}")
    pass

...

This method is useful when you know the page has a button that will load the next set of content. You can also use this method to click on other elements that will trigger the next set of content to load. The scroll_into_view_if_needed method will scroll the button or element into view if it is not already visible on the page. This is one of those scenarios when you will want to double-check the page actions with headless=False to see if the button is being clicked and the content is being loaded as expected before running a full crawl.

Note: As mentioned above, confirm that the page assets(.js) are loading correctly and that the network requests are being made so that the button (or element) is mounted and clickable.

Wrapping Up

Web crawling is a case-by-case scenario and you will need to adjust the code to fit the page that you are trying to scrape. The above code is a starting point to get you going with crawling infinite scroll pages with Scrapy and Playwright.

Hopefully, this helps to get you unblocked! 🙌

Subscribe to get my latest content by email -> Newsletter

Building and deploying a Slack app with Python, Bolt, and AWS Amplify

siegerts — Mon, 15 Jul 2024 14:21:04 +0000

Slack apps and bots are a handy way to automate and streamline repetitive tasks. Slack's Bolt framework consolidates the different mechanisms to capture and interact with Slack events into a single library.

From the Slack Bolt documentation:

All flavors of Bolt are equipped to help you build apps and integrations with our most commonly used features.

Install your app using OAuth 2.0
Receive real time events and messages with the Events API
Compose rich, interactive messages with Block Kit
Respond to slash commands, shortcuts, and interactive messages
Use a wide library of Web API methods

In my experience, this has made it straight forward to combine functionality instead of having multiple apps all handling different elements of Slack's API ecosystem.

There is a ton that you can do combining this library with the Amplify toolchain. So, let's create an app using Python 🐍!

We'll create a simple Slack app that's triggered when the /start-process slash command is run from within Slack.

Set up your Amplify project

This is the standard procedure. The project name used is slackamplify.

? Enter a name for the project slackamplify
The following configuration will be applied:

Project information
| Name: slackamplify
| Environment: dev
| Default editor: Visual Studio Code
| App type: javascript
| Javascript framework: none
| Source Directory Path: src
| Distribution Directory Path: dist
| Build Command: npm run-script build
| Start Command: npm run-script start

Add a REST API with a Lambda function

The REST API is the lifeline of the Slack app. This API will be called each time the slash command is invoked from within Slack.

amplify add api

For the API path, I use a base path (/) below. If you something specific here, make sure to append that path to your base URL endpoint when configuring the Slack app below.

? Please select from one of the below mentioned services: REST
? Provide a friendly name for your resource to be used as a label for this category in the project: slackpython
? Provide a path (e.g., /book/{isbn}): /
? Choose a Lambda source Create a new Lambda function
? Provide an AWS Lambda function name: slackpythonfunction
? Choose the runtime that you want to use: Python
Only one template found - using Hello World by default.

Available advanced settings:
- Resource access permissions
- Scheduled recurring invocation
- Lambda layers configuration

? Do you want to configure advanced settings? No
? Do you want to edit the local lambda function now? No
Successfully added resource slackpythonfunction locally.

Set up the function's virtual environment

On to the function!

But first, we need to update the function's Python virtual environment.

Install the Python dependencies

The next step is very important!

Change into the function's directory!

cd <project>/amplify/backend/function/<function-name>

To install dependencies, you'll need to first activate the Python virtual environment (below) for this function. To do this, you need to be in the function directory (step above). I've seen this trip folks up when folks actually install dependencies into the global Python installation and not into the correct virtual environment. The Amplify CLI will will prep your function directory for Pipenv if you select the Python runtime for your function during the amplify add api prompts.

TIP
A quick reminder - Pipenv differs slightly from other Python virtual environment tooling:

pipenv shell activates the environment
exit deactivates the environment

Activate the virtual environment

pipenv shell

I like to think of each Amplify function as it's own isolated environment where the code (i.e. functionality) pairs 1:1 with the dependencies within that environment. And for each function, you can have your own isolated Python virtual environment environment.

Note

If you want to share dependencies, or code, across functions then you'll want to check out the Lambda Layers capability in the Amplify CLI to see if that fits your use case.

Now, install the required dependencies:

pipenv install slack_bolt

After installing the first dependency, you will see a Pipfile.lock file in the directory.

pipenv install python-lambda

The Pipfile will now list the above dependencies that you installed.

  [[source]]
  name = "pypi"
  url = "https://pypi.org/simple"
  verify_ssl = true

  [dev-packages]

  [packages]
  src = {editable = true, path = "./src"}
+ slack-bolt = "*"
+ python-lambda = "*"

  [requires]
  python_version = "3.8"

Update the Lambda function

At this point, we'll use the the placeholder Lambda function from the Example with AWS Lambda in the Bolt documentation. It may be collapsed and at the bottom of the page, so double check that you're looking at the right snippet.

# reference example from: https://slack.dev/bolt-python/concepts#lazy-listeners

from slack_bolt import App
from slack_bolt.adapter.aws_lambda import SlackRequestHandler

# process_before_response must be True when running on FaaS
app = App(process_before_response=True)

def respond_to_slack_within_3_seconds(body, ack):
    text = body.get("text")
    if text is None or len(text) == 0:
        ack("Usage: /start-process (description here)")
    else:
        ack(f"Accepted! (task: {body['text']})")

import time
def run_long_process(respond, body):
    time.sleep(5)  # longer than 3 seconds
    respond(f"Completed! (task: {body['text']})")

app.command("/start-process")(
    ack=respond_to_slack_within_3_seconds,  # responsible for calling `ack()`
    lazy=[run_long_process]  # unable to call `ack()` / can have multiple functions
)

def handler(event, context):
    slack_handler = SlackRequestHandler(app=app)
    return slack_handler.handle(event, context)

I recommend reading through this GitHub thread to get a better understanding of process_before_response, ack(), and lazy= in the code above. These elements make it possible to run this an application like this in a serverless environment without the need for a persistent long-running server.

Adjusting the function's IAM policy

You'll need to add the adjust policy below for your Lambda function as mentioned in the Bolt docs.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "lambda:InvokeFunction",
                "lambda:GetFunction"
            ],
            "Resource": "*"
        }
    ]
}

To do so, adjust the lambdaexecutionpolicy in the /amplify/backend/function/<function-name>/<function-name>-cloudformation-template.json to add the above statement.

"lambdaexecutionpolicy": {
    "DependsOn": ["LambdaExecutionRole"],
    "Type": "AWS::IAM::Policy",
    "Properties": {
        "PolicyName": "lambda-execution-policy",
        "Roles": [{ "Ref": "LambdaExecutionRole" }],
        "PolicyDocument": {
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Effect": "Allow",
                    "Action": ["logs:CreateLogGroup",
                    "logs:CreateLogStream",
                    "logs:PutLogEvents"],
                    "Resource": { "Fn::Sub": [ "arn:aws:logs:${region}:${account}:log-group:/aws/lambda/${lambda}:log-stream:*", { "region": {"Ref": "AWS::Region"}, "account": {"Ref": "AWS::AccountId"}, "lambda": {"Ref": "LambdaFunction"}} ]}
                 },
+                {
+                   "Sid": "VisualEditor0",
+                   "Effect": "Allow",
+                   "Action": [
+                      "lambda:InvokeFunction",
+                      "lambda:GetFunction"
+                   ],
+                   "Resource": "*"
+               }
             ]
         }
     }
 }

Push the API

amplify push

And create the resources 🚀

✔ Successfully pulled backend environment dev from the cloud.

Current Environment: dev

| Category | Resource name       | Operation | Provider plugin   |
| -------- | ------------------- | --------- | ----------------- |
| Function | slackpythonfunction | Create    | awscloudformation |
| Api      | slackpython         | Create    | awscloudformation |
? Are you sure you want to continue? (Y/n) Yes

Once this is deployed, the URL can be used in the next step (Create the Slack app).

REST API endpoint: https://<id>.execute-api.<region>.amazonaws.com/dev

We now have 90% of the Slack app deployed. The app needs environment variables to be complete but we can only get those once we create a new app in Slack. So, let's do that.

Create the Slack app

Now, you'll need to head over to Slack to create (if it doesn't exist) and link the app to the Amplify API.

Go to https://api.slack.com/apps and Create new app > From scratch. Use the endpoint from the API above!

Select Name & workspace

Basic information > Add features & functionality > Slash commands

Basic information > Install your app

Update the Lambda function's environment variables

Slack will generate the required tokens and secrets that you'll need to populate into your function with environment variables once the app and command are set up.

Add the below variable/token pairs to the function in Lambda. To add environment variables, go to Configuration > Environment variables in the AWS Console for the Lambda function.

SLACK_SIGNING_SECRET: Basic information > App credentials
SLACK_BOT_TOKEN : OAuth & Permissions > starts with xoxo-

Test the command in Slack

Awesome! Now let's test the slash command.

It shows in the command menu.

And...the command runs as expected when submitted along with some data.

Conclusion

There you have it! A Slack app running in Lambda created with AWS Amplify running in a serverless context.

I'd definitely take a look at the other ways that you can listen and respond to messages. My favorite? Responding to reactions...

@app.message(":wave:")
def say_hello(message, say):
    user = message['user']
    say(f"Hi there, <@{user}>!")

TIP

Once you start listening for other events, you'll need to verify your endpoint configuration. For example, some events require that the endpoint URL end with /slack/events.

Hope that helps! 🚀

If you have any questions or feedback, feel free to reach out on X @siegerts.

Subscribe to get my latest content by email -> Newsletter

Verifying Lemon Squeezy Subscription Webhooks in Cloudflare Workers

siegerts — Thu, 27 Jun 2024 15:33:55 +0000

I've been using Lemon Squeezy to handle subscription billing in several projects. Lemon Squeezy offers an easy way to manage subscriptions and payments, similar to the DX of Stripe, but includes tax remittance and compliance as a Merchant of Record (MoR). So, using Lemon Squeezy helps offload the complexities of tax, compliance, and dispute handling. Additionally, I like the idea of having the built-in email marketing and affiliate portal as optional features.

This is a high-level overview of how I use Cloudflare Workers and D1 to verify and save Lemon Squeezy subscription webhook data. I wanted to do this without enabling Node.js compatibility in the Worker.

Note: This assumes that you have an understanding of Cloudflare Workers, D1, and have set up a Lemon Squeezy webhook endpoint for your product.

Webhook Management and Integration

The management of subscription lifecycles in Lemon Squeezy is handled through webhooks, which notify a specified URL upon subscription events—similar to Stripe’s webhook system. For a recent project, I used Cloudflare Workers to accept these webhooks and D1 to manage subscription data in a SQLite database. Opting for a serverless, lightweight architecture was important, especially since this is only handling a few API endpoints.

My requirements for this included:

A hosted checkout page ✅
Use of a custom domain ✅
Ability to exclusively sell products via in-app purchases, removing them from the main store ✅
Capability to pass user metadata to the checkout page ✅
Follow a similar subscription model to what I'm used to with Stripe ✅

Checkout lifecycle

When users click the upgrade/checkout link within the app, they are redirected to a Lemon Squeezy hosted checkout page. Here, users input their details and payment information to create a subscription.

The URL generated from within the app that points to the hosted checkout page includes necessary user details passed as query parameters. For example, the URL might look like this (using template literals in JavaScript/TypeScript):

`${baseCheckoutUrl}?checkout[email]=${user.email}&checkout[custom][uid]=${user.uid}`

These parameters (checkout[email] and checkout[custom][uid]) pass the user's email and UID to the checkout page, linking them with the newly created subscription. The UID is used as a unique identifier for the user in the database.

Warning: There's an edge case to consider: If a user can change their email address or navigates directly to the checkout page without a UID meta param, discrepancies might occur between the webhook payload and the user’s actual details. This issue should be considered when managing webhook responses and communicating with users in post-purchase scenarios.

Using Workers Routes

When a subscription is created, Lemon Squeezy sends a webhook to the specified URL. In this setup, the URL is a Cloudflare Worker that receives requests at the /api/v1/ls/webhook endpoint.

To consolidate the handling of the site and API under the same domain, I use Workers Routes to route /api/* to the Cloudflare Worker and /* to the main site. This setup allows me to manage all of the site's operations under the same domain, managed by Cloudflare.

Cloudflare Workers Routes

Project Structure

This is a high-level overview of the Worker structure. In this app, this is the only API endpoint in index.ts, but you can add more routes as needed.

.
├─ db
│  └─ schema.ts
├─ lib
│  └─ utils.ts
├─ src
│  └─ index.ts
├─ wrangler.toml
...

Using Cloudflare D1

In this example, the database schema is defined in the schema.ts file and includes a customer table with columns for the uid, email, orderId, productId, and createdAt timestamp.

// db/schema.ts

import { sql } from 'drizzle-orm';
import { text, integer, sqliteTable } from 'drizzle-orm/sqlite-core';

export const customer = sqliteTable('customer', {
  uid: text('uid').primaryKey(),
  email: text('email').notNull(),
  orderId: text('order_id').notNull(),
  productId: integer('product_id', { mode: 'number' }).notNull(),
  createdAt: text('created_at')
    .notNull()
    .default(sql`CURRENT_TIMESTAMP`),
});

The use of D1 is very compelling for this setup since the entire 1/ API is located in Cloudflare, 2/ it's SQL-based and works well with Drizzle ORM, and 3/ the overhead to maintain is minimal. The drizzle-orm package is used to interact with the database and execute SQL queries.

Verifying Lemon Squeezy webhooks in a Cloudflare Worker

The index.ts file contains the main logic for the Worker. The Worker listens for POST requests on the /api/v1/ls/webhook endpoint and verifies the request signature using the secret provided by Lemon Squeezy.

The Worker uses Hono, a lightweight framework for Cloudflare Workers, to handle requests. The framework provides middleware, routing, and other features to simplify the development of Workers. The Worker also uses Drizzle to interact with the D1 database.

// src/index.ts

import { Hono } from 'hono';
import { logger } from 'hono/logger';
import { drizzle } from 'drizzle-orm/d1';
import { customer } from './../db/schema';

type Env = {
  DB: D1Database;
  LS_WEBHOOK_SECRET: string;
};

const app = new Hono<{ Bindings: Env }>();

app.use(logger());

app.post('/api/v1/ls/webhook', async (c) => {
  if (c.req.method !== 'POST') {
    return c.json({ error: 'Method not allowed' }, 405);
  }

  const secret = c.env.LS_WEBHOOK_SECRET;
  const signature = c.req.header('x-signature');

  if (!signature || !secret) {
    return c.json({ error: 'Unauthorized' }, 401);
  }

  const key = await crypto.subtle.importKey(
    'raw', 
    new TextEncoder().encode(secret), 
    { name: 'HMAC', hash: 'SHA-256' }, 
    false, 
    ['verify']
  );

  const body = await c.req.text();
  const rawBody = new TextEncoder().encode(body);

  const verified = await crypto.subtle.verify(
    'HMAC', 
    key, 
    hexToUint8Array(signature!), 
    rawBody
  );

  if (!verified) {
    return c.json({ error: 'Unauthorized' }, 401);
  }

  const bodyJson = JSON.parse(body);

  const eventName = bodyJson?.meta?.event_name;

  // handle additional events as needed
  if (eventName && eventName !== 'subscription_created') {
    return c.json({ error: 'Event not supported' }, 400);
  }

  // change/adjust as needed
  const guid = bodyJson?.meta?.custom_data?.uid;
  const email = bodyJson?.data?.attributes?.user_email;
  const identifier = bodyJson?.data?.attributes?.identifier;
  const productId = bodyJson?.data?.attributes?.first_order_item?.product_id;

  if (!guid || !email || !identifier || !productId) {
    return c.json({ error: 'Invalid request' }, 400);
  }

  const db = drizzle(c.env.DB);

  await db
    .insert(customer)
    .values({ uid: guid, email, orderId: identifier, productId })
    .onConflictDoUpdate({ target: customer.uid, set: { productId } });

  return c.json(200);

});

To process the verification, Cloudflare Workers support the Web Crypto API through the SubtleCrypto interface, which is accessible via crypto.subtle. The Worker first checks if the request method is POST and extracts the signature from the request headers. It then verifies the signature using the secret provided by Lemon Squeezy. If the signature is valid, the Worker continues processing the request.

The hexToUint8Array function is a utility function that converts a hex string to a Uint8Array. Uint8Array is used by the Web Crypto API for cryptographic operations.

// utils.ts
export function hexToUint8Array(hex: string) {
  const matched = hex.match(/.{1,2}/g);
  return new Uint8Array(matched ? matched.map((byte) => parseInt(byte, 16)) : []);
}

The custom_data?.uid custom data is the user ID passed to the checkout page as a query parameter and is accessed in the meta object of the webhook payload.

The Worker then parses the request body as JSON and extracts the event name, user email, order ID, and product ID from the request. The Worker checks if the event name is subscription_created and inserts the user details into the database using the Drizzle ORM. The Worker returns a 200 status code if the request is successful.

This code also assumes that the D1 database binding is configured in the wrangler.toml file. The database configuration includes the database name, database ID, and migrations directory.

# wrangler.toml
...

[[d1_databases]]
binding = "DB"
database_name = "<database-name>"
database_id = "<database-id>"
migrations_dir = "drizzle"

Then, the database configuration can be accessed as an environment variable in the Worker using c.env.DB binding.

Configuring the webhook signing secret

For the Lemon Squeezy webhook request to be verified, the webhook secret signature needs to be stored as a Cloudflare Worker secret and then retrieved from the environment.

I use the Wrangler CLI to create the secret:

npx wrangler secret put LS_WEBHOOK_SECRET

The secret can then be accessed in the Worker using c.env.LS_WEBHOOK_SECRET.

Note

The difference between secrets and environment variables is that secrets are encrypted and stored securely by Cloudflare. The environment variables are plaintext and can be accessed by anyone with access to the Worker code (config toml) or console access.

This setup uses Cloudflare Workers and D1 to handle Lemon Squeezy subscription webhooks in a serverless architecture. You can easily extend this setup to handle additional events, API routes, and integrate with other services. It's straightforward to set up and maintain, and the lightweight architecture has been ideal so far.

👋 If you have any questions or feedback, feel free to reach out on X @siegerts.

Subscribe to get my latest content by email -> Newsletter

Detecting GitHub Issue Transfers in Chrome Extensions

siegerts — Tue, 25 Jun 2024 15:33:55 +0000

In GitHub issues, if an issue is transferred to another repository or if the issue is converted to a discussion (or vice versa), the URL reference will change. Still it's not always easy to track these changes. Tracking transfers is pretty tricky, even using the GitHub API. If you're listening for webhook events on issues, it is possible to catch the transferred event but you won't know where the issue was transferred to.

In dossi, the extension listens for these URL changes in the browser and stores the URL in the storage. When the URL changes, the extension checks if the URL is a redirect. If a redirect (transfer) is detected, the UI will notify the user.

An example of a redirect is when an issue is transferred to another repository in GitHub. Or, if the organization or repository name changes, the URL will change.

Here's a video of how this works:

This is something that I wanted to account for after running into this issue when tracking issue transfers in the past. Mainly, these links get shared around and included in docs, Slack and Discord messages, and other places. If the issue is transferred, I didn't want to lose the reference to the issue. It's a nuanced edge case but it can cause some head-scratching when you're trying to track issues across repositories or organizations.

How to track issue transfers (side quest)

I've solved this in the past with the GitHub API but that requires warehousing of all of the issues (typically from an organization) in order to catch the transfer event and then check for the existence of the issue in another repository. In short, you need to check for "duplicates" of the issue in other repositories. Here's an example of how I've queried for this in the past using the GitHub API and a warehouse of issue data:

-- SQL query to find duplicate issues in a database
-- username is the issue creator
SELECT *
FROM issues
WHERE
    username || created_at in(
        SELECT
            username || created_at AS id FROM issues
        GROUP BY
            created_at, username
        HAVING
            count(*) > 1)
ORDER BY
    created_at, title, updated_at;

Reference: contributor-metrics GitHub repository

This will isolate issues that have been created at the same time by the same user - which is a good indicator that the issue has been transferred since the issue will appear in two different repositories. Then it's possible to ping the issues and check if the returned status is a 301 with a new location header.

Tracking issue transfers in dossi

dossi uses the chrome.webNavigation API to listen for URL changes in the browser and stores the URL in the storage. When the URL changes, the extension checks if the URL is a redirect. If it is, it stores the redirect URL in the storage.

This is useful for tracking the URL changes in the browser and is available using the chrome.webNavigation API. To use this API, you'll need to add the webNavigation permission in the extension manifest.

{
  "permissions": ["webNavigation"]
}

You can add handlers to trigger for specific URL patterns using the originAndPathMatches property in chrome.webNavigation. In dossi, I'm using this to check for changes in discussions, issues, pull requests, and repositories in GitHub.

Here's an example of how this is implemented in the background script of the extension:

// using the plasmohq/storage library
import { Storage } from "@plasmohq/storage"
const storage = new Storage()


type UrlMatch = {
  url: string
  pos: number
} | null

type Redirect = {
  to: string
  from: string
}


const patterns = [
  {
    originAndPathMatches: `^https://github\.com/[a-zA-Z0-9\-_]+/[a-zA-Z0-9\-_]+/discussions/[0-9]+$`,
  },
  {
    originAndPathMatches: `^https://github\.com/[a-zA-Z0-9\-_]+/[a-zA-Z0-9\-_]+/issues/[0-9]+$`,
  },
  {
    originAndPathMatches: `^https://github\.com/[a-zA-Z0-9\-_]+/[a-zA-Z0-9\-_]+/pulls/[0-9]+$`,
  },
  {
    originAndPathMatches: `^https://github\.com/[a-zA-Z0-9\-_]+/[a-zA-Z0-9\-_]+$`,
  },
  { originAndPathMatches: `^https://github\.com/[a-zA-Z0-9\-_]+$` },
]


patterns.forEach((pattern, pos) => {
  chrome.webNavigation.onBeforeNavigate.addListener(
    async (details) => {
      await storage.set("from", { url: details.url, pos } as UrlMatch)
    },
    { url: [pattern] }
  )
  chrome.webNavigation.onCommitted.addListener(
    async (details) => {
      await storage.remove("redirect")

      if (details.transitionQualifiers.includes("server_redirect")) {
        logger.log("server_redirect detected.")

        let from: UrlMatch | null = await storage.get<UrlMatch>("from")

        if (!from) {
          return
        }

        const to = { url: details.url, pos } as UrlMatch

        if (from && to && from?.url !== to?.url && from?.pos == to?.pos) {
          await storage.set("redirect", {
            from: from?.url,
            to: to?.url,
          } as Redirect)

          // remove from storage
          await storage.remove("from")
        }
      }
    },
    { url: [pattern] }
  )
})

The patterns array contains the URL patterns that the extension listens for.
The chrome.webNavigation.onBeforeNavigate event listener is triggered when the URL is about to change. The current URL is stored in the storage.
The chrome.webNavigation.onCommitted event listener is triggered when the URL has changed. If the URL has a server_redirect transition qualifier, the extension checks if the URL has changed and if the URL is the same as the URL stored in the onBeforeNavigate event listener. If the URL has changed but the pattern type is the same, the extension stores the redirect URL in the storage.
The UI then displays a notification to the user in the side panel overlay.

Note: The server_redirect transition qualifier is one or more redirects caused by HTTP headers sent from the server happened during the navigation.

Request lifecycle breakdown

The pattern index (pos) is used to map the URL pattern to the URL stored in the onBeforeNavigate event listener. This is used to check if the changed URL type is the same as the type of the onCommitted URL.

So, an example of a GitHub issue transfer will follow this sequence of events:

URL with a pattern for *GitHub issue fires in onBeforeNavigate event listener
URL with a pattern for GitHub issue fires in onCommitted event listener
URLs are not the same but the positional mapping is the same
server_redirect is detected
This indicates that the GitHub issue has been transferred

*GitHub issue pattern: ^https://github\.com/[a-zA-Z0-9\-_]+/[a-zA-Z0-9\-_]+/issues/[0-9]+$

Surfacing the Redirects in the Extension

The extension uses the chrome.storage API to store the redirect URL. When the extension is opened, it checks if there is a redirect URL in the storage and displays a notification to the user in the side panel overlay.

The user can choose to view the notes and transfer them to the correct entity (i.e. new issue/repo URL).

Wrapping up

If you only work across a few repositories then you may not hit this issue often. But if you're working across multiple repositories or organizations, this situation is likely to pop up. I wanted a way to capture these changes without having to query the GitHub API for every issue in every repository or track events via webhooks. This ended up being a nice in-between solution that works well client-side but also gives users the option to review the changes.

The dossi browser extension and the web app are both open source. Check them out on GitHub:

The extension is available in the Chrome Web Store. If you have any questions or feedback, feel free to reach out on X @siegerts.

Bring Your Own API Key: Supporting User-Provided OpenAI Keys and Prompts in Browser Extensions

siegerts — Mon, 24 Jun 2024 05:34:21 +0000

I recently added support (v1.1.0+) for bringing your OpenAI API to dossi as an opt-in feature. This allows users to use their own OpenAI API key and prompts in the browser extension alongside parsed GitHub issue and discussion content.

These are just a few thoughts on the implementation and some of my considerations when adding this in.

Overview

It was important to me that the addition strikes a balance between allowing the generative AI functionality and not being too prescriptive in how it’s used.

An example is in the video below. A user has enables the feature, adds their API key, and then adds a prompt. Then, the prompt is available to use when viewing a GitHub issue page and clicking the Prompts button. The prompt messages are composed of the user's input (previous notes) and the parsed GitHub issue. Then, the prompt is sent to the OpenAI API and the response is displayed in the extension. This response can be edited and saved as a new note.

In dossi, the Gen AI prompt functionality is a nice-to-have that can enhance the experience for users already using OpenAI for other projects. Or, for users who already use the OpenAI API.

Some common use cases for using prompts in dossi include:

Generating summaries of GitHub issues and discussions
Creating reproducible steps for bug reports
Monitoring the sentiment of a conversation
Determining contributors to an issue or discussion
Staying up to date on the latest comments and discussions in a repository

To me, this can be a helpful tool for users who are managing multiple repositories, projects, or open-source organizations in GitHub. It can help them quickly get up to speed on the current state of an issue or discussion and help to reduce the overall time to close and triage for issues.

Considerations for adding Gen AI

There are a few things to consider when adding this type of functionality. This isn't specific to dossi, but more of a general pattern that I've seen in other extensions that are backed by a hosted API and part of the reason why I decided to allow users to bring their own API key.

Note that this is more geared towards SaaS-type browser extensions.

Extensions backed by hosted API that integrates with LLM model providers...

Pricing model: Typically a flat rate subscription fee, usage (credit) based, or both. This complicates the tracking of usage and billing for the user and couples the extension to the API provider.
Abuse: Since the extension is a client-side application, users can abuse the API. This could be in the form of excessive requests or malicious content. Even if the user is subscribed to dossi, they may try to refute the charges after using the LLM functionality.
User-defined input: Accepting, processing, and relying on arbitrary input (like GitHub issues) has a bunch of edge cases to account for (more on counting prompt input tokens below)
Prompt response formatting: Everything works well until it doesn't. The response from the LLM model may not be what the user expects. This could be due to the prompt, the input, or the model itself.
Handling errors without UX degradation

Allowing users to bring their own key eliminates most of the concerns. This also makes the functionality completely opt-in. The UX of the extension won't be impacted if a user doesn't want to use it.

Adding Gen AI to dossi

Here's the high-level overview of the implementation in dossi:

Options Page - Allow users to toggle on or off the use of their own API key. If enabled, a user can add their OpenAI API key and add in their own custom prompts. Once prompts exist, the UI button will be present when navigating GitHub issue and discussion pages.
Local Storage - In dossi, these settings are only saved on the local browser using the storage.local. These settings are never sent to our servers or persisted in a remote database. This is different from the note, pin, and label data that is persisted in a hosted database.
Prompts button - The button is only visible when a user is on a GitHub issue or discussion page. The button is only visible if the user has enabled the feature, added an API key, and added at least one prompt.
Gen AI - The prompt is constructed using the user's input and the parsed GitHub issue or discussion. The prompt is sent to the OpenAI API and the response is displayed in the extension. The user can edit the response and save it as a new note.
Error Handling - Since this is the user's API key, I'm able to surface errors directly from the OpenAI SDK in the UI. Since the actions to configure the API key and prompts in dossi were explicit, the user has some awareness of the context of the error.

All of the messaging passes through the background service worker of the extension.

Creating an Options Page

I decided to add an options page to the extension to make it easier and less cluttered to configure the local settings. Unlike the Chrome Side Panel API, an options page can be programmatically opened. This makes it convenient and more natural for users to navigate to. I added a settings link that triggers the page open in the extension user dropdown menus.

// background.ts

chrome.runtime.onMessage.addListener(function (request, sender, sendResponse) {
  if (request.action === "openOptionsPage") {
    chrome.runtime.openOptionsPage()
  }
})

This is referenced in the user menu that is shared across the extension popup and content script side panel overlay.

// user-account-nav.tsx
<DropdownMenuItem
   onClick={() =>
     chrome.runtime.sendMessage({ action: "openOptionsPage" })
}>
  Settings
</DropdownMenuItem>

Adding an API key and prompts

This options page provides a way for users to opt-in to API key use. Currently, if opted-out, then the side panel prompt button in the extension will not be displayed. This makes the functionality completely opt-in and will not clutter the UI if a user isn't interested in using it.

Options page in dossi

If enabled, a user can add their API key and add in their own custom prompts. Once prompts exist, the UI button will be present when navigating GitHub issue and discussion pages.

Adding a prompt in dossi local settings

Since dossi is used with GitHub, a valid prompt for issues and discussion can be pretty broad. A few factors quickly come to mind:

Is the user browsing, using, or maintaining the repo?
What is the programming language used?
Is the issue a bug, feature request, or question?
Is subject matter expertise required?
Is the /repo public or private?
What is primary written language of the content?

I'd rather leave it up to the users to determine what information is the most useful for them.

Saving configuration locally with Chrome Storage

Note
Always set spending limits on your API keys and monitor usage. The allowed permissions for the be as minimal as possible to reduce the risk of abuse.

Persisting data locally with Chrome storage is always a bit tricky. In dossi, these settings are only local.

This puts the control in the hands of the user. From a security perspective, there is no need for the extension or web app to store and manage user API keys on remote servers. If at any time a user wants to delete or invalidate their API key for use with dossi, they have at least 4 options:

Delete the API key at the provider level (i.e. OpenAI)
Clear all of their local dossi settings in the option page
Overwrite their stored API key with a new or invalid one
Remove the dossi extension (uninstall) which will wipe all of the associated storage data as per the Chrome API

Any of these actions can be done by the user, at any time. The note data, on the other hand, is remotely stored for a few reasons:

The data also powers the web app and additional integrations for users (i.e. reporting)
Storing large amounts of data locally may require additional browser extension permissions (unlimitedData )
Complex data models are difficult to troubleshoot, extend, rollback, and version - especially once published and in use

Using the OpenAI JavaScript SDK

The OpenAI JavaScript SDK is used to interact with the OpenAI API. To use the functionality, users are required to create an OpenAI API key and grant write access for Model Capabilities and grant allowed models at the project level (i.e. gpt-4o ).

OpenAI API key settings

For the initial implementation, users can define the core prompt content, maxTokens, and model (currently gpt-4o). For reference, here is the prompt schema using zod. Currently, the only available model is gpt-4o and provider is OpenAI.

// This is the initial shape of the prompt
const promptSchema = z.object({
  title: z
    .string()
    .min(3, { message: "Title must be at least 3 chars" })
    .max(25, { message: "Title must be less than 25 chars" }),
  content: z
    .string()
    .min(25, { message: "Content must be at least 50 chars" })
    .max(1000, { message: "Content must be less than 1000 chars" }),
  model: z
    .string()
    .nonempty()
    .refine((m) => models.includes(m), {
      message: "Invalid model",
    }),
  maxTokens: z.coerce
    .number()
    .min(50, { message: "Max tokens must be between 50 and 1000" })
    .max(1000, { message: "Max tokens must be between 50 and 1000" }),
})

These parameters are passed along with 1) the parsed page, and 2) any previous dossi notes for the page (i.e. dossi entity) to include as context.

const openai = new OpenAI({
  apiKey: apiKey,
  dangerouslyAllowBrowser: true,
})

// previous notes from user
const contextNotes = entity?.notes
  ?.map((note) => `${note.createdAt} ${note.content}`)
  .join("\n")

const promptInput = `
  ${prompt?.content}
  ---
  ${input}
`

const messages: ChatCompletionMessageParam[] = [
  {
    role: "system",
    content: "You are a helpful technical assistant.",
  },
  ...(contextNotes
    ? ([
        {
          role: "user",
          content: `Past notes for context: ${contextNotes}`,
        },
      ] as ChatCompletionMessageParam[])
    : []),
  { role: "user", content: promptInput },
]

I think in the future, including the previous user notes will be optional. The dangerouslyAllowBrowser flag is set to true to allow the OpenAI SDK to be used in the browser. This is a requirement since the request is coming from the content script and not the background service worker.

let chatCompletion: ChatCompletion

try {
  chatCompletion = await openai.chat.completions.create({
    messages: messages,
    model: prompt?.model,
    max_tokens: prompt?.maxTokens,
    n: 1,
    stop: null,
    temperature: 0.2,
  })
} catch (error) {
  console.error(error)
  // surface error to user
  ...
}

Not hiding the implementation

By just providing the guardrails, I feel like it actually makes the use of the LLM functionality more tangible. The user shares control of the prompt input and output. Because of this, I feel like it gives the extension a bit more flexibility in what it does vs. the perceived "what it could do" of a completely hidden implementation. Also, the extension is open source, so users can inspect the code and see how it works.

Surfacing errors

The first instance is presenting the user with errors. Since this is the user's API key and they own the configuration of that key, I'm able to surface errors directly from the OpenAI SDK in the UI. Since the actions to configure the API key and prompts in dossi are explicit, the user has some awareness of the context of the error.

Surfaced OpenAI API error in dossi

I'm assuming that the user has some familiarity with the OpenAI API and can troubleshoot the error. If the error is related to the prompt, the user can edit the prompt and try again. If the error is related to the API key, the user can check the key and try again.

Editing the prompt response

Secondly, the user can edit the prompt response directly in the extension and save it as a new note. This is a nice way to allow the user to review and update the response and make it more useful for their needs. Also, it's a nice way to smooth over any errors that may have occurred in the initial response.

Flexibility on edge cases

There are a lot of edge cases when manually constructing prompts and including arbitrary (and unknown) input context in the form of parsed GitHub issues. The first is model token limitations. Models have constraints on the amount of input tokens, output tokens, and sometimes a combination. One approach to account for this is to count the prompt tokens before sending them to the model to gauge whether the prompt will meet the criteria. To be honest, this isn't on my radar to add.

This is a challenge in dossi since a GitHub issue may be extremely long with historical data. Additionally, bundling the dependencies into the extension may cause the size to increase impacting the overall experience for a user.

I've decided to allow these types of errors to surface to the user instead of trying to intelligently truncate the context which could change the overall intent. Also, since this is the user's API key, I don't want to trigger additional calls to the completion APIs (i.e. chunk and summarize) without their explicit actions since there will be associated costs.

I may add a feature in the future to allow the user to manually truncate the input context if they are running into token limitations. Or, at a minimum, allow the parsed GitHub content to be viewed in the extension before sending the prompt to the model.

Moving forward

Hope that you found this interesting! This is just the first iteration of the generative AI functionality in dossi. I'm excited to see how it's used.

The browser extension and the web app are both open source. Check them out on GitHub:

The extension is available in the Chrome Web Store.

If you have any questions or feedback, feel free to reach out on X @siegerts.

Subscribe to get my latest content by email -> Newsletter

dossi is now open source

siegerts — Sun, 05 May 2024 00:33:55 +0000

Backstory

I built dossi as a way to keep track of my own notes for GitHub issues and pull requests across multiple repositories and organizations.

Personally, a challenge that I kept running into was just saving general thoughts at the moment when I found a new open-source project or issue that I knew I'd want to come back to later. Initially, this was to help with issue triage and reproducibility.

For organizations that I was a part of, I wanted something more private than just having the GitHub visibility set to private (just for myself). I felt that the existing tools were too focused on teams building and collaborating on code, and not enough on the experience of those that are also supporting customers and users of the software. Later, I found that I was able to track increases in interest (reactions) on issues and keep track of the general sentiment around a request or issue.

Yes, there are GitHub notifications and stars, but that quickly becomes overwhelming especially when you're working across an organization or multiple organizations with a lot of repositories, in addition to your own personal projects.

Features

Sidepanel overlay on GitHub pages to add, edit, and delete notes
- Label creation
- Pin pages to view later
- Note management (create, read, update, delete, sort) with "light" markdown support
Extension Popup window to view recent activity and pins
Content script button to open the sidepanel overlay and display the number of notes for the current page
Transferred page detection to prompt the user to transfer notes to the new page entity
Web app to view all notes across all repositories and organizations

Development

The project (obviously) started as a closed source project. I wasn't 100% sure which direction to take it and, quite honestly, it just started as a fun project to build. This was also my first time building a browser extension so there were a lot of unknowns on how it would shape up.

Browser extensions definitely have their own set of challenges, especially when it comes to the UI and UX. I used the Plasmo extension framework to get started quickly, iterate fast, and not have to worry about the boilerplate code that comes with building a browser extension especially when it comes to the Manifest v3 configuration.

Most of the time spent was the parity between the extension and the web app with the UI look and feel. Extension content script styling has some challenges since you can have collisions with the host page's CSS. dossi uses shadcn/ui for the UI components which makes it easy to keep the UI look and feel consistent across the extension and the web app - but uses Tailwind for the styling. GitHub also uses Tailwind so there are challenges that require some overrides to make sure the UI components look consistent across the extension and the web app.

Separating the extension and web app

The first decision is the separation of functionality between the browser extension and the web app.

Thinking back, I could have forgone the web app and just used the browser extension as the main interface. That may be something to consider in the future and would simplify the architecture quite a bit. I wanted to have a meta-view of all of the notes across all of the repositories and organizations that I was keeping track of - and filter and search across them.

That said, there is some nice flexibility in having the API separate from the extension.

A few things come to mind...

Storage schema management

Changes to the storage schema can be managed in the API (and API versioning) and not have to worry about the extension and the extension review process that can take a few days to publish an updated version

Chrome storage API

Using the chrome.storage API is flexible but backward compatibility can be a challenge. Typically, the first suggestion is to use a storage library or database but troubleshooting client-side migrations for users usually requires an uninstall/reinstall of the extension. This is not ideal for a user who has a lot of notes saved since they will lose all of their notes. Users will likely just stop using the extension if they have to do this.

Data model complexity

The mental model of the Storage API can get complex quickly when the extension interacts with it in multiple ways across background scripts, content scripts, and popup scripts.

Meta datatable view

The web app can be used as a backup for notes and also as a way to view notes across multiple devices. This is something that I thought could be a potential use case in the future.

Allow notes to be used outside of the extension

It felt limiting to restrict the notes to just the extension. I wanted to be able to use the notes in other applications and services. This is something that I haven't fully explored yet but I think it could be a powerful feature to have.

Integration with other services

I've given thought to integrating with other services like Slack, Discord, and email to send notifications and reminders about notes that are saved. And, also the ability to share notes with other users (or organizations) that are also using dossi.

Auth state management

The extension and web app use NextAuth.js for authentication. This was a decision to reduce the friction of auth state between the extension and the web app. The extension uses the NextAuth.js client to authenticate and uses the host permissions of the extension to use the session cookie to authenticate with the API. The host permissions are set to the API of the web app. This allows the extension to use the session cookie to authenticate with the API and not have to worry about the Chrome storage API to manage the auth state. Also, if a user is already authenticated with the web app, they will be automatically authenticated with the extension. This is a nice feature to have since the extension can be used across multiple devices and the auth state is managed in one place.

That said, although users sign in with their GitHub account, the GitHub API is not used for data access or retrieval. This was a decision to keep the notes private and not have to worry about the GitHub API rate limits. Also, I was contemplating expanding the notes to other services and didn't want to be tied to the GitHub API.

The interaction between the extension and the web app is shown in the diagram below:

Tech stack

The tech stack was largely driven by the use of Next.js, NextAuth.js, Prisma, and shadcn/ui. I've recently migrated the database to a serverless Postgres database using Neon Postgres from MySQL (more on this in a future post). Locally, I build and test using a development database branch using Neon branches. I'd like to lean more into Postgres features and extensions in the future.

Here's a breakdown of what's used in different parts of the project:

Tech	Description	Browser extension	Web app	API
Plasmo	browser extension framework	✅
TypeScript	language	✅	✅	✅
shadcn/ui	UI components	✅	✅
Tailwind	CSS	✅	✅
TanStack/react-query	data fetching	✅
zod	schema validation	✅	✅	✅
Next.js	framework		✅
Neon Postgres	Serverless Postgres database		✅	✅
Prisma	database ORM and client		✅	✅
NextAuth.js	auth	✅	✅	✅
Stripe	payments		✅
Vercel	deployments and hosting		✅

As and aside, the use of TanStack/react-query was a game changer for me. I was able to remove a lot of boilerplate code for syncing data in the extension. I was able to consolidate the data fetching and caching logic.

Deployment

The API is hosted on Vercel and the extension is hosted on the Chrome Web Store and Firefox Add-ons. The extension submission process differs between the Chrome Web Store and Firefox Add-ons.

For the extension, I haven't automated the end-to-end testing and deployment process. I like to spot the builds and versioning before uploading the artifacts to the web stores.

The web app and API are integrated with the GitHub repos and automatically deploy on push to the main branch.

Future plans

Overall, I'm excited to see what the community does with the project. It seemed a bit daunting to transition the project to open source but I'm excited to see how the project can be used in other ways that I haven't thought of yet.

I've already received some feedback and feature requests that I'm excited to work on, so stay tuned for updates.

If you have any feedback or feature requests, feel free to open an issue on the GitHub repositories below or reach out to me on Twitter/X @siegerts.

The extension is available in the Chrome Web Store.

If you have any questions or feedback, feel free to reach out on X @siegerts.

Move Fast and “Branch” Things

siegerts — Mon, 15 Apr 2024 16:38:10 +0000

Neon simplifies the use of scalable Postgres, changing how you handle your database infrastructure from development through production. This is a fundamental shift in how to leverage your Postgres infrastructure. Instead of spending time on Infrastructure as code (IaC) and cloud-specific configuration tasks in services like Amazon RDS or Google Cloud SQL, with Neon you can increase developer velocity and focus on building for your customer.

When making architecture decisions for any app, it is always important to consider the constraints of your system and under what circumstances those constraints and requirements apply, both during periods of low request traffic and during high-traffic bursts. Neon maintains Postgres compatibility while enhancing the developer experience with database branching, autoscaling, and serverless scale to zero – enabling you to launch and scale your projects quickly.

Neon is the most productive way for builders to use Postgres.

Minimizing Total Cost of Ownership (TCO) in Database Infrastructure

A traditional vendor database setup requires a complex architecture involving virtual private clouds (VPCs), subnet configurations, and manual replication configurations across availability zones. Another aspect of this setup is managing access, typically done through a bastion host or a jump box, which serves as a gateway for updates or connections to the data source.

Implementing features like High Availability (HA) and autoscaling in these environments further complicates the architecture. For example, this is a subset of considerations to take into account when provisioning an RDS instance in AWS:

Complex Setup and Maintenance : Configuring an instance requires attention to numerous settings, making the setup and ongoing maintenance a complex task.
Scaling Challenges : Properly scaling an instance to match fluctuating applications requires understanding of workload patterns, optimized instance types, and auto-scaling policies.
High Availability : Ensuring continuous availability requires additional setup and planning.
Cost Management : Deciding instance types, storage, and backup options to balance performance and total expense.
Security Management and Networking : Correctly configuring VPCs, security groups, and Identity and Access Management (IAM) roles.
Backup and Recovery : Configuring and managing backups.

Additionally, these architectures lack the advantages of a truly serverless architecture that can scale to zero, increasing cost, complexity, and resource demands. This complexity results in a significant investment of time, both initially and for ongoing maintenance, introducing a steep learning curve.

All of this is needed before even using the database.

These factors combined contribute to a higher total cost of ownership, especially when considering how such an architecture integrates with the broader ecosystem of your application.

Want scale to zero serverless?

Neon is scale-to-zero Postgres. No changes are needed. Your compute scales down (to idle) when not in use and scales up in capacity to handle increased requests and manage capacity. This also results in cost savings for production-like environments. Your environments can be exact copies of each other in dev/test/prod but not incur additional costs when not in use or receiving traffic. Additional services, proxies, or cloud event logging aren’t needed. Enough said.

True serverless architecture can significantly transform the way a managed Postgres platform is utilized. This transition can improve developer productivity by allowing them to concentrate on creating value, while also enhancing the scalability and availability of applications. This leads to quicker development cycles and increased reliability of the applications.

Need connection pooling?

Without Neon that is a separate configuration, piece of infrastructure to manage, and service fee. With Neon, it’s included. Neon supports connection pooling using PgBouncer, which allows your database on Neon to support up to 10,000 concurrent connections.

Want your database to autoscale?

Neon dynamically adjusts the amount of compute resources allocated to a Neon compute endpoint in response to the current load, eliminating the need for manual intervention. This is autoscaling-on-the-fly.

Without Neon, you’re faced with either managing the autoscaling yourself by monitoring and adjusting instance types and policies with RDS, or settling for increased cold starts and lack of scale to zero with Aurora (20-60s on Aurora V1). Even with Aurora V2 and RDS, you’ll likely need to use connection pooling (above). This means you might have to set up Amazon RDS Proxy or run PgBouncer on a separate Amazon Elastic Compute Cloud (Amazon EC2) instance to manage your database connections.

Move fast and “branch” things

Neon’s database branching enables you to clone databases in ~1 second. Until you’ve experienced Neon Postgres Branching – you don’t know what you’re missing. A branch is a copy-on-write clone of your data, making it possible to perform operations on branches independently without impacting the original data. This is a different way to think about the database. Instead of just a piece of infrastructure – Neon is like Git for Postgres. With that in mind, you start to envision different ways to use the database to accelerate your workflow, not just ways to manage the database.

Interacting with your Postgres database in a similar way to using git unlocks workflows for teams, feature dev, and test environments have for a long time been an operational burden – and has been a task reserved for DevOps teams.

It’s possible to create a Postgres database branch with one CLI command:

This is not possible with other Postgres vendors.

In seconds, you can branch your entire database as shown in the video below:

Neon’s separation of storage and compute makes this possible – allowing for flexible and independent scaling of each. For comparison, to isolate development/test/production database environments in a traditional cloud environment, each of these environments would require the provisioning of a separate database cluster or database within a cluster for isolation. It’s not possible to branch your Postgres database in this manner with other vendors.

To isolate a new Postgres database in Amazon RDS or Aurora Postgres, the only option is to create a new instance or replicate an existing one. This task, while ultimately not providing the equivalent outcome, is significantly more complex and time-consuming. Creating a new RDS Postgres instance takes ~5 minutes. This also does not account for the role and policy IAM updates, new infra, and additional storage costs for the copy.

Neon branching empowers developers to take a more iterative and experimental development approach, allowing for rapid prototyping and testing without risk to the production environment, accelerating development feedback loops and innovation.

Branching is easy, cost-effective, and fast.

Neon branches create an entire copy of your Postgres Cluster. Branches can then be used to isolate tests, analyses, and new feature launches without compromising the integrity of the main branch. Because of this, it’s even easier to perform data recovery or roll back to a previous version of the database. By restoring a specific branch, developers can recover data efficiently, a task that is more time-consuming with traditional vendor solutions. This adds an extra layer of security and flexibility, enabling teams to manage their data with greater agility and minimizes the potential for data loss.

Neon branches collapse the timeline from hours, days, or weeks into seconds.

Developer Workflow Integration

With just a connection string, Neon enables developers to take full advantage of Postgres. This puts the database in the hands of the developer without sacrificing the scalability, reliability, and performance of a production-grade developer experience. Your existing Postgres workflow and toolset works with Neon since Neon is Postgres. This includes Integrated Development Environments (IDEs) and framework integrations like Django, Rails, Node.js, etc. These will all work without the use of cloud vendor-specific SDKs (and dependencies).

Additionally, developers can manage and connect to Neon using open-source tools: the Neon CLI for direct command-line interaction, the Neon API for programmatic access and integration, and the Neon Serverless Driver, which works within serverless architectures and runtimes.

Neon Command Line Interface (CLI)

The integration of the Neon CLI with development tools and CI/CD pipelines enhances developer workflows, reducing the friction associated with database-related operations like creating projects, new databases, and branches. Once you have your connection string, you can manage your entire Neon database. This makes it possible to quickly set up deployment pipelines such as GitHub Actions, GitLab CI/CD, or Vercel Preview Environments. These operations and pipelines can also be treated as code and live alongside your applications as they evolve and mature.

This integration translates to quicker deployments, easier rollback processes, and a more robust deployment experience, all contributing to increased developer velocity. Or, these operations can be made using the Neon API across different languages and frameworks.

Below is a video to demonstrate how to restore a Neon Postgres database in just a few seconds:

Connect from Serverless Environments

The Neon Serverless Driver for JavaScript and TypeScript is a low-latency Postgres driver for JavaScript and TypeScript that allows you to query data from serverless and edge environments over HTTP or WebSockets where direct access to TCP is restricted.

This can be used in serverless environments like AWS Lambda, Cloudflare Workers, and Vercel Edge functions. With a few lines of code, you can connect to and query your database the same way that you would in a backend persistent server instance.

import { neon } from '@neondatabase/serverless';
const sql = neon(process.env.DATABASE_URL);
...

const [post] = await sql`SELECT * FROM posts WHERE id = ${postId}`

This keeps the programming model consistent – developers can use Neon the same way that they would normally use Postgres but with an enhanced and flexible experience.

Postgres as a Developer Tool

With the movement away from Postgres as just a piece of infrastructure, developers can (and should) view Neon Postgres as an instrumental tool to enhance the scalability and functionality of their applications and workloads. Two examples are in Generative AI and Software as a Service (SaaS) applications.

Leveraging AI in your application

Use Neon Postgres with the pgvector extension as the way to store vector embeddings and enhance your models using Retrieval Augmented Generation (RAG) with vector search.

Neon can scale up on-demand to build your index and scale back down to save on cost. This on-demand scaling can lead to cost savings compared to traditional, always-on database instances that are overprovisioned to accommodate peak usage periods.

Building SaaS platforms

The streamlined experience of using Neon to use Postgres makes it even more possible to build Software as a service (SaaS) platforms that have requirements to rapidly provision Postgres and even isolate those instances across tenants using database branching. With traditional cloud vendors, this is costly and operationally intense – in terms of provisioning time, maintenance, and cost.

Neon helps to unblock these use cases and empower SaaS builders to take full advantage of Postgres on a per customer or tenant basis. Effectively allowing SaaS businesses to provide their Platform as a Service (PaaS).

Conclusion

Neon abstracts away the complexities traditionally associated with database management—such as infrastructure setup, connection pooling, and autoscaling—Neon allows developers and builders to concentrate on what they do best: building innovative and scalable web applications…fast.

To get started with Serverless Postgres, sign up and try Neon for free. Follow us on Twitter/X, join us on Discord, and let us know how we can help you build the next generation of applications.

Fullstack Serverless CI/CD in AWS Amplify Hosting with Postgres Database Branching

siegerts — Wed, 06 Mar 2024 23:50:49 +0000

This post will guide you through integrating AWS Amplify Hosting CI/CD with Neon Postgres with a focus on testing your application’s environment or feature branches using real data enabled by Neon’s database branching. This architecture automates your workflow and ensures each new feature or environment branch in your Amplify application has a corresponding, isolated database. This is especially useful if you’re building and deploying a Server Side Rendering (SSR) application using frameworks like Next.js, Nuxt, Astro, and SvelteKit.

Because both Neon and Amplify Hosting are serverless, the underlying infrastructure doesn’t require maintenance. Also, when not in use, both services scale down to zero. For Amplify Hosting, this involves serverless compute functions (i.e SSR), while for Neon, it pertains to the Postgres cluster compute.

Solution Overview

In this guide, we cover the deployment process of a serverless full-stack app using Amplify Hosting, leveraging its SSR compute capabilities. SSR enables running code and logic in a server environment, useful for tasks like using routing middleware, interfacing with third-party services, or connecting to a database.

To follow along, check out the YouTube video below that walks through in depth the process of deploying, and verifying the database branch creation in Neon when deploying a Nuxt SSR app that uses an Amplify Gen 2 backend with Amplify Auth. While the example features Nuxt for server-side APIs, the methodology applies to any SSR framework compatible with Amplify Hosting’s function-based compute.

For practical implementation, the scripts referenced in this guide (and video) are located in the Neon Branches with Amplify Hosting CI/CD repo on GitHub.

AWS Amplify Hosting

AWS Amplify Hosting is a fully managed CI/CD and hosting service that supports static sites, single-page applications (SPAs), and full-stack serverless SSR apps.

In Amplify Hosting, a typical workflow involves teams managing app branches that align with various environments, such as development, testing, and production. Each branch, like dev, test, and prod, corresponds to its respective environment and is accessible via a unique URL, which incorporates the first-level subdomain and the branch identifier. For example, https://<branch-name>.<amplify-app-id>.amplifyapp.com/.

Serverless Postgres

When developing an SSR app in AWS Amplify Hosting and requiring Postgres or an RDBMS, the choices for a serverless relational database are limited. It’s important that your database can handle your application traffic without manual adjustment since serverless SSR fullstack apps can scale out in response to bursts of request traffic. And then scale back down when not in use – similar to how Lambda (and cloud) functions operate.

Using Amazon RDS involves virtual private cloud (VPC) and architecture configurations, typically requiring a Lambda function or service proxy for database access to bridge the connection from Amplify Hosting to the VPC. Alternatively, directly exposing an RDS database online requires setting up Amazon RDS Proxy, essentially acting as PgBouncer, for scaling purposes.

Amazon DynamoDB (DDB) is another serverless database solution, but it doesn’t offer the relational capabilities inherent to RDBMS like Postgres, such as relational data models, complex joins, or transactions.

Neon is serverless Postgres with auto-scaling, easy setup, built-in connection pooling, and database branching. Neon’s branching capability allows developers to clone their entire Postgres cluster in seconds, creating isolated environments for testing new features without affecting the primary database branch. For these reasons, it pairs well with the serverless nature of Amplify Hosting and frontend fullstack SSR application architectures.

Amplify Hosting CI/CD Integration

This Amplify Hosting SSR app and Neon Postgres integration involves a custom Bash script (neon-ci.sh) to manage Neon database branches alongside Amplify app branches. This script dynamically updates the .env file’s DATABASE_URL environment variable with the database connection string for each branch. This .env file is then loaded into the application’s server-side runtime as environment variables. To interact with the Postgres database in serverless or edge contexts, the Neon Serverless Driver for JavaScript and TypeScript can be used. Additionally, database migrations can be integrated into the CI/CD pipeline since the connection string is available in the build time environment.

Here’s how the integration works

A new Git branch is created and pushed in a repo that is configured for fullstack continuous deployments in Amplify Hosting
During the CI/CD process, a new Neon Postgres branch will be created using the Neon CLI via a custom bash script
This branch’s connection string is injected into the DATABASE_URL parameter within a .env file.
The application is deployed and has access to the DATABASE_URL environment variable in server-side compute functions
Connect to your database using the Neon serverless driver

In order to set up this flow, you’ll need to complete the following steps

Set up your Amplify app and CI/CD pipeline as per your project requirements
Choose the Amazon Linux: 2023 build image and enable automatic service role creation (if you are not using another role)
Copy the neon-ci.sh script and amplify.yml build settings into the root of your app directory
Enable branch auto-detection for the app to create a new Amplify app branch for each new Git branch matching the configured pattern
Create a Neon project and create an API key
Create an SSM SecureString parameter for the Neon API key
Add the correct policy permissions to the Amplify app Service role for SSM Parameter Store and Amplify from the AWS CLI within the CI/CD build time
Modify neon-ci.sh invocation in your amplify.yml build settings with your specific Neon project ID, database name, and other parameters as needed
Push your changes and monitor the Amplify console for the deployment status – the Neon console will show the created branch(es)

Configuring Amplify Hosting Build Settings

To set up build settings in Amplify Hosting, first connect your code repository to AWS Amplify Hosting to activate the CI/CD pipeline. Amplify supports GitHub, Bitbucket, GitLab, or AWS CodeCommit as source control providers.

Create an Amplify app

Confirm the app settings

Choose the build image for your application (i.e. Amazon Linux: 2023) and enable automatic service role creation (if you are not using another role). This role will be updated to allow access to your Neon API key parameter in SSM Parameter Store.

Update the Amplify Hosting Build Settings

The app build settings are configured in the Amplify Hosting console or checked in as amplify.ymlwithin your code repository.

This amplify.yml file defines the CI/CD pipeline configuration for AWS Amplify Hosting. It is split into backend and frontend stages, with specific commands executed at different phases ( preBuild , build , and postBuild ) for both the backend and frontend stages.

Customize the build process by adjusting the amplify.yml file, which controls the actions taken during the CI/CD pipeline stages for both frontend and backend components.

version: 1
backend:
  phases:
    preBuild:
      commands:
        - sudo yum -y install jq
        - jq --version
        - npm i -g neonctl@v1
    build:
      commands:
        - nvm use 18
        - corepack enable
        - pnpm install
        - |
          if ["${AWS_BRANCH}" = "main"] || ["${AWS_BRANCH}" = "dev"]; then 
            pnpm amplify pipeline-deploy --branch $AWS_BRANCH --app-id $AWS_APP_ID
          else
            pnpm amplify generate config --branch main --app-id $AWS_APP_ID 
          fi

          bash neon-ci.sh create-branch --app-id $AWS_APP_ID --neon-project-id &lt;neon-project-id&gt; --branch-name $AWS_BRANCH --parent-branch main --api-key-param "&lt;ssm-param&gt;" --role-name &lt;neon-role&gt; --database-name &lt;neon-db-name&gt; --suspend-timeout 0
  cache:
    paths:
      - $(pnpm store path)
frontend:
  phases:
    preBuild:
      commands:
        - nvm use 18
        - corepack enable
        - npx --yes nypm i
    build:
      commands:
        - npm run build

  artifacts:
    baseDirectory: .amplify-hosting
    files:
      - "**/*"

Adjust as needed depending on your app framework requirements, and also make sure to update the neon-ci.sh input arguments. The following is a step-by-step breakdown of the sample amplify.ymlset up:

Backend:

Pre-Build Phase:
1. Installs jq for JSON processing
2. Installs the neonctl CLI tool globally using npm
Build Phase:
1. Sets the Node version using nvm and enables corepack for package manager version management
2. Based on the branch (main or dev), it deploys the backend Amplify app and then invokes the neon-ci.sh script to manage Neon database branches

Frontend:

Sets up Node, installs dependencies, and executes the build process for the frontend

Cache Configuration:

Caches the pnpm store path to enhance the speed of future builds

Creating a new Postgres Database in Neon

Visit the Neon Console, sign up, and create your first project by following the prompts in the UI. Then, create an API key for your Neon account. This key should be stored in SSM Parameter Store and accessed by your Amplify build scripts for authentication with Neon for database branching. Whether you’re working with an existing project or starting a new one, this project will host the database linked to your Amplify SSR app. When you create a new branch in the Amplify app, a corresponding database branch is automatically created in your specified Neon project.

Add the Neon CI bash script

Include the Neon bash CI script in your application directory. This will be referenced during the backend build stage of the CI/CD pipeline. This script can be modified, if needed, to account for your specific use case but the primary function is to create a branch for each Amplify app branch and retrieve the connection string.

The script has the following commands and options:

/neon-ci.sh &lt;command&gt; [options]

Commands
create-branch:
    Creates a new Neon database branch.

options:
    --app-id &lt;app-id&gt;
    --neon-project-id &lt;project-id&gt;
    --parent-branch-id &lt;parent-branch-id&gt;
    --api-key-param &lt;api-key-param&gt;
    --role-name &lt;role-name&gt;
    --database-name &lt;database-name&gt;
    --suspend-timeout &lt;suspend-timeout&gt;

cleanup-branches:
    Cleans up Neon database branches that no longer
    have corresponding Amplify app branches.

options:
    --app-id &lt;app-id&gt;
    --neon-project-id &lt;project-id&gt;
    --api-key-param &lt;api-key-param&gt;

These commands, specifically create-branch, are used during the backend build phase of the CI/CD process.

Update the Amplify Hosting app backend build role with the correct policy statements

Update the Amplify Hosting backend build role with the policies below to allow access to SSM Parameter Store and Amplify using the AWS CLI within the CI/CD build environment. The neon-ci bash script calls out to SSM and Amplify which will require the service role to have the correct permissions to access.

An example of this from the bash script:

# neon-ci.sh
...

function set_neon_api_key {
    export NEON_API_KEY=$(aws ssm get-parameter --name $NEON_API_KEY_PARAM --with-decryption --query Parameter.Value --output text)
    if [[-z "${NEON_API_KEY}"]]; then
        echo "ERROR: NEON_API_KEY is not set. Exiting."
        exit 1
    fi
}

...

To update the role, add the below inline policies to the Amplify app backend build role in AWS Identity and Access Management (IAM). Scope these resources as required by your app.

For SSM Parameter Store

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowAmplifySSMCalls",
      "Effect": "Allow",
      "Action": [
        "ssm:GetParametersByPath",
        "ssm:GetParameters",
        "ssm:GetParameter"
      ],
      "Resource": ["arn:aws:ssm:*:*:parameter/&lt;name-of-your-parameter&gt;"]
    }
  ]
}

For AWS Amplify access

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Statement1",
      "Effect": "Allow",
      "Action": "amplify:ListBranches",
      "Resource": "arn:aws:amplify:*:*:apps/*/branches/*"
    }
  ]
}

Enable branch auto-detection for the app to create a new Amplify app branch

Update the applications repository settings to enable branch auto-detection. Once enabled, a new app branch will automatically create new Amplify app branches when a new Git branch is created and pushed to the repo.

Post build database branch clean up

If you want to automate database branch cleanup after each build, then you can include logic to use the clean up branches function in the Neon CI bash script. The cleanup-branches function will pull all of your Amplify Hosting app branch references with the aws cli and then compare those with the branch names in your Neon project.

_ Note: Make sure to test any destructive branch actions on test apps and branches first before deploying to production CI/CD pipelines._

...

postBuild:
        commands:
          - # EXAMPLE: only run the cleanup-branches command if you have tested 
          - |
            if ! ["${AWS_BRANCH}" = "main"] &amp;&amp; ! ["${AWS_BRANCH}" = "dev"]; then
              # bash neon-ci.sh cleanup-branches --app-id $AWS_APP_ID --neon-project-id &lt;neon-project-id&gt; --api-key-param "&lt;ssm-param&gt;"
            fi

...

Connecting to Postgres with Nuxt SSR Server Routes

Now, you can use the Neon Serverless Driver to connect to your database. For example, using Nuxt SSR in Amplify Hosting with server routes, you can query your database branch using a similar pattern as below:

// ./server/routes/api/shows.ts

import { neon } from "@neondatabase/serverless";
const { databaseUrl } = useRuntimeConfig();
const sql = neon(databaseUrl!);

export default defineEventHandler(async (event) =&gt; {

  const shows = await sql`SELECT * FROM netflix_shows limit 10`;

  return {
    shows,
  };
});

The environment variable is populated into Nuxt with useRuntimeConfig().

// nuxt.config.js

export default defineNuxtConfig({
  devtools: { enabled: true },
  runtimeConfig: {
    // The private keys which are only available within server-side
    databaseUrl: process.env.DATABASE_URL,

    // Keys within public, will be also exposed to the client-side
    public: {
      //
    },
  },
});

Best Practices and Considerations

Securely manage your Neon API key. Do not commit this key to git. Use a SSM Parameter Store SecureString to store and access your Neon API key securely within your build environment.
Implement logging within your build scripts to track the creation and deletion of database branches. This will be useful for troubleshooting and auditing your CI/CD process.
Integrate database migration scripts into your CI/CD pipeline to update the schema of your database branches automatically when necessary. Drizzle and Prisma can be integrated into your build process for this using the database branch connection string environment variable.

Conclusion

Integrating Neon database branches with Amplify Hosting CI/CD provides a flexible way to automate environment isolation and database creation – in a truly serverless way.

To get started with incorporating Serverless Postgres into your Amplify Hosting SSR apps, sign up and try Neon for free. Follow us on Twitter and join us in Discord to share your experiences, suggestions, and challenges.

Deploy a Serverless FastAPI App with Neon Postgres and AWS App Runner at any scale

siegerts — Fri, 09 Feb 2024 17:16:46 +0000

In this post, we’ll guide you through setting up a scalable serverless API using FastAPI, deployed on AWS App Runner and powered by Neon Postgres as the serverless database.

FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.8+ based on standard Python type hints. The key features of FastAPI are its speed and ease of use, making it an excellent choice for building robust APIs. FastAPI has quickly become a go-to framework for setting up Python APIs and services.

AWS App Runner is a fully managed service that makes it easy for developers to quickly deploy containerized web applications and APIs, at scale. These services will automatically scale the instances up or down for your App Runner application in accordance to incoming traffic volume.

Neon complements this setup by providing a serverless Postgres database that scales compute resources automatically, optimizing performance based on demand.

We’ll walk through deploying a FastAPI application with Neon Serverless Postgres, focusing on secure database connection management via AWS Systems Manager (SSM) Parameter Store. This approach allows for flexible application environment management across development, testing, and production stages.

Let’s get started!

Prerequisites

To follow along and deploy the application in this guide, you will need:

An AWS account, with access to AWS App Runner for deploying and managing your application
A GitHub or BitBucket account, for linking to AWS App Runner and enabling CI/CD functionality
A Neon account – The FastAPI app will connect to a Neon serverless Postgres database 🚀

We’ll start by setting up a local development environment and getting our application running. Then, we’ll connect the application to a Neon Postgres database to ensure it can scale efficiently. Finally, we’ll set up automatic deployment through AWS App Runner, which will deploy our application upon each commit to a Git repository.

This infrastructure provides a flexible architecture that will scale automatically as needed by the API.

Set up FastAPI with Poetry

In this app, we’ll use poetry to manage the dependencies in the local Python virtual environment. For reference, the Python version used to write this post is 3.11. This version will also match the App Runner Python 3.11 runtime during deployment.

To start, use poetry to create a new project:

poetry new fastapi-neon

This will create a project structure that we’ll use to build out the FastAPI app.

fastapi-neon
├── pyproject.toml
├── README.md
├── fastapi-neon
│ └── __init__.py
└── tests
    └── __init__.py

Next, initialize a new git repository within the project directory.

git init

Once the app is working locally, you’ll push the repo to GitHub and then deploy to AWS App Runner using the built-in CI/CD workflow.

Installing FastAPI and uvicorn

To isolate project dependencies, poetry will create a Python virtual environment associated with the project. To serve the application, we’ll use uvicorn.

Now, using poetry (or your preferred dependency manager), install fastapi and uvicorn.

poetry add fastapi "uvicorn[standard]"

Now, add a _ main.py _ app into the fastapi_neon app directory and serve the app:

# fastapi_neon/main.py
from typing import Union
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: Union[str, None] = None):
    return {"item_id": item_id, "q": q}

Serve the app locally with the following command:

poetry run uvicorn fastapi_neon.main:app --host 0.0.0.0 --port 8000

Awesome! The app will be functional on your local machine. Check the Swagger UI endpoint by visiting http://0.0.0.0:8000/docs.

Updating the application to connect to Neon

Now that we have an app working locally, we’ll connect the application code to a Neon Postgres database.

For configuration management, we’ll use the Starlette configuration pattern. This will make it possible to reference predefined environment variables. FastAPI is based on Starlette, so we’ll be able to use this functionality without adding an additional dependency.

To connect to a Postgres database from the app, we’ll add an SQLModel (based on SQLAlchemy). SQLModel is a library for interacting with SQL databases from Python code, with Python objects.

Since SQLModel is driver agnostic, we’ll need to install a Postgres driver to enable it to connect to Neon. For this, we’ll use psycopg 3.

Add the sqlmodel and psycopg dependencies:

poetry add sqlmodel "psycopg[binary]"

Note: The default driver behavior for SQLAlchemy is to look for/use psycopg2. If you plan on using psycopg2 then you’ll need to install psycopg2-binary and adjust the connection string formatting in the create_engine code below.

Now, replace the existing main.py application code with the app code below:

# fastapi_neon/main.py
from contextlib import asynccontextmanager
from typing import Union, Optional
from fastapi_neon import settings
from sqlmodel import Field, Session, SQLModel, create_engine, select

from fastapi import FastAPI

class Todo(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    content: str = Field(index=True)

# only needed for psycopg 3 - replace postgresql
# with postgresql+psycopg in settings.DATABASE_URL
connection_string = str(settings.DATABASE_URL).replace(
    "postgresql", "postgresql+psycopg"
)

# recycle connections after 5 minutes
# to correspond with the compute scale down
engine = create_engine(
    connection_string, connect_args={"sslmode": "require"}, pool_recycle=300
)

def create_db_and_tables():
    SQLModel.metadata.create_all(engine)

# The first part of the function, before the yield, will
# be executed before the application starts
@asynccontextmanager
async def lifespan(app: FastAPI):
    print("Creating tables..")
    create_db_and_tables()
    yield

app = FastAPI(lifespan=lifespan)

@app.get("/")
def read_root():
    return {"Hello": "World"}

@app.post("/todos/")
def create_todo(todo: Todo):
    with Session(engine) as session:
        session.add(todo)
        session.commit()
        session.refresh(todo)
        return todo

@app.get("/todos/")
def read_todos():
    with Session(engine) as session:
        todos = session.exec(select(Todo)).all()
        return todos

This example API allows clients to create (POST) and retrieve (GET) todos. The database connection string is imported from settings and used to instantiate the connection in create_engine. All of the values are cast as Secret to limit their exposure in logs in the event that they are exposed.

Lifespan events are the recommended way to execute code once the server starts in FastAPI. In this example, the Todo model (i.e. table) is created if it doesn’t yet exist in the database.

The pool_recycle=300 option is an “optimistic” approach to prevent the pool from using a connection that has passed a certain age. In this case, we are setting the value to 5 minutes to correspond with the default compute auto-suspend in Neon.

Another option to account for possible stale connections is to use the pool_pre_ping option. This option is used to test the availability of a database connection before the connection is used. Note, this can add additional latency to new connections since they are first “checked”.

Next, we’ll get the connection string for the database.

Integrate Neon Postgres with FastAPI

Create a settings.py file in the fastapi_neon directory alongside main.py. This will reference the DATABASE_URL environment variable. During local development, this value will be populated from an _ .env _ file.

# fastapi_neon/settings.py
from starlette.config import Config
from starlette.datastructures import Secret

try:
   config = Config(".env")
except FileNotFoundError:
   config = Config()

DATABASE_URL = config("DATABASE_URL", cast=Secret)

Create a .env file in the root of your project and add the DATABASE_URL variable:

# .env
# Don't commit this to source control
# Eg. Include &quot;.env&quot; in your `.gitignore` file.
DATABASE_URL=

Note: Do not commit the .env file to source control. Add .env to the .gitignore file to prevent this file from being committed and pushed. This environment variable in this file will only be used during local development.

Visit the Neon Console, sign up, and create your first project by following the prompts in the UI. You can use an existing project or create another if you’ve already used Neon.

Visit the project Dashboard, check the Pooled connection option, and select the Connection string option from the Connection Details panel.

The connection string will be in the following format:

postgres://alex:AbC123dEf@ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech/dbname?sslmode=require

Set this value as your DATABASE_URL in the .env file. Now, test the application by running the following to start the app server locally:

poetry run uvicorn fastapi_neon.main:app --host 0.0.0.0 --port 8000

The app is live…locally!

The application is now using Neon Postgres as the connected database. The create_db_and_tables lifespan event created the todo model (table) in the database. You can double-check this by going into the Neon console and viewing the tables in your Neon project – you will see todo listed.

You can insert and fetch todos from the API by using the live endpoints. For example, try sending some requests using the built-in FastAPI Swagger UI docs endpoint at http://0.0.0.0:8000/docs.

Now, it’s time to deploy the app to AWS App Runner.

Setting up the AWS App Runner configuration

A few items need to be in place before the app can be deployed to App Runner. Mainly, the database connection string will need to be stored in AWS Systems Manager (SSM) Parameter Store. Then, an apprunner.yaml configuration file will be added to the project that instructs App Runner how to build and run the app. This is also where the database connection string variable is referenced and associated with the app.

At a high-level, the steps are as follows. Subsequent sections will guide you through each of these:

Create the apprunner.yaml configuration file in the root of the project directory
Create a DATABASE_URL parameter in SSM Parameter Store
Update the apprunner.yaml secret value with the SSM parameter ARN to inject the database connection string into the runtime environment
Create an instance role that App Runner can use to access the SSM Parameter Store Secure String secret
Push to GitHub or BitBucket and set up the deployment in the AWS App Runner console

Create the App Runner apprunner.yaml configuration

In your project directory, create an apprunner.yaml configuration file with the following structure.

version: 1.0
runtime: python311
build:
  commands:
    build:
      - echo "Build command..."
run:
  runtime-version: 3.11
  pre-run:
    - echo "Installing dependencies..."
    - pip3 install poetry
    - poetry config virtualenvs.create false
    - poetry install

  command: poetry run uvicorn fastapi_neon.main:app --host 0.0.0.0 --port 8000
  network:
    port: 8000
  secrets:
    - name: DATABASE_URL
      value-from: "<replace-with-param-arn>"

This configuration instructs App Runner to install, build, and run the app. The specified managed runtime is the revised Python 3.11 App Runner build. When the app is pulled from the git repo, the dependencies defined in the poetry.loc k file are installed, then the app is served using the same uvicorn command from the local environment. You’ll notice that there is a placeholder for the value-from entry in the secrets sections. We’ll update this next.

_Note: The App Runner CI process is very strict when parsing the configuration. Make sure to check the indentation and that the file name is not abbreviated and ends with .yaml. _

Create a DATABASE_URL parameter in SSM Parameter Store

Go to AWS Systems Manager and navigate to Application Management > Parameter Store and click Create Parameter.

Enter the following for Name and Type:

Name: /fastapi-neon/DATABASE_URL
Type: SecureString

For the value, use the database connection URL from your Neon dashboard that you’ve tested with previously.

Click Create parameter. Once created, click on the newly created parameter and copy the ARN identifier.

Now, replace the placeholder (<replace-with-param-arn>)value in apprunner.yaml in secrets > value-from with this ARN.

...
secrets:
   - name: DATABASE_URL
     value-from: "<replace-with-param-arn>"
...

And save.

Push to Source Control

The final project directory structure will be:

.
├── fastapi_neon
│ ├── __init__.py
│ ├── main.py 
│ └── settings.py
├── tests/
├── apprunner.yaml
├── poetry.lock
├── pyproject.toml
├── README.md
├── .gitignore
...

Confirm that .env* is included in the .gitignore file in the root of the project.

# Environments
.env*
...

Commit and push the code to a repo in GitHub or BitBucket. Remember, do not commit the .env file.

Create an App Runner instance role

In order for the App Runner process to access the SSM Parameter Store secret, we’ll need to create an instance role with the appropriate permissions to access the SSM resource and attach it to the App Runner service when we create the service.

Go to the AWS Identity and Access Management (IAM) console and click Create role.

Select Custom trust policy and add the JSON policy below:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "tasks.apprunner.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Click Next and skip adding permissions
Click Next and enter the below information
1. Role name : app-runner-fastapi-role
Click Create Role

Now, open the new app-runner-fastapi-role. Select Create inline policy in the Permissions tab.

In the JSON editor, add the following permission policy with the parameter /fastapi-neon/DATABASE_URL ARN from above:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "ssm:GetParameters",
            "Resource": "<add-the-param-arn>"
        }
    ]
}

The above permissions allow the App Runner instance role to access the SSM parameter(s) that contains the database connection string.

Click Next. In the Policy details section, add:

Policy name : apprunner-ssm-policy

Finally, click Create policy.

Deploying the application to AWS App Runner

Finally, we are in App Runner. Let’s deploy this service!

Go to AWS App Runner and click Create an App Runner service.

This service will use a Source code repository since it will be pulling the code from the repo that was just created. You will need to allow App Runner to access the repo in your account if you have not already authorized the AWS Connector.

Select your git provider and repository details. In Deployment settings , Automatic is selected to deploy the app on each push to the linked branch.

Click Next. On the next screen, select Use a configuration file. This will instruct App Runner to use the apprunner.yaml configuration file from the repo. Click Next.

In the Configure service section:

Add a Service name for your app in Service settings
In Security , select the instance role that was created earlier.

The trust relationship that was specified during role creation is what determines if it is available in the dropdown options 🙂.

Click Next. Next, review the setup and click Create & deploy.

This may take a few minutes to deploy…

Once successfully deployed, test the FastAPI service at https://<service-id>.<region>.awsapprunner.com/docs. For example, if you add data to the table using the SQL Editor in the Neon console:

INSERT INTO todo (content) VALUES ('Task 1.');
INSERT INTO todo (content) VALUES ('Task 2.');
INSERT INTO todo (content) VALUES ('Task 3.');

Then you can fetch that data by accessing https://<service-id>.<region>.awsapprunner.com/todos/.

Clean up

To wrap up, delete the application if it’s no longer needed. To do this, go into the App Runner service and select Actions > Delete to remove the app.

Conclusion

Integrating AWS App Runner and Neon Serverless Postgres is an effective way to deploy a robust, scalable serverless FastAPI service. Neon’s unique autoscaling capabilities ensure that your database resources adapt to your application’s demands without manual intervention. This dynamic scalability is crucial for maintaining optimal performance and cost efficiency during off-peak times and traffic bursts. This is perfect for growing teams that want to increase their development velocity while keeping their architecture flexible.

To get started with incorporating Serverless Postgres into your FastAPI and Python apps, sign up and try Neon for free. And, join us in our Discord server to share your experiences, suggestions, and challenges.

Resources

The code for this guide is in the fastapi-apprunner-neon repo on GitHub

Deploying a FastAPI backend using AWS Amplify Container-based REST APIs

siegerts — Thu, 13 May 2021 21:17:35 +0000

No surprise that it's a difficult process to go from development to production deployments in an organization 🤷.

This is especially true for analytics and data science teams developing models or business logic. There's usually not a clear path or tooling to support application hand-offs or deployments across teams.

One way to bridge the gap between applications is to allow for service-to-service communication. REST APIs are great for this type of use-case. Especially when auto-generated, interactive documentation, is available out-of-the-box 😉.

AWS Amplify provides a great option for this - Serverless containers using API Gateway + AWS Fargate.

This guide will follow the steps outlined in the Serverless containers section of the Amplify documentation and the FastAPI Docker Deployment documentation to quickly create and deploy a production-ready, scalable REST API.

Prerequisites

You'll need to have the below installed and configured.

AWS Amplify CLI - working with Amplify (I'm using v4.50.2 )
Docker - testing the APIs locally

FastAPI

As mentioned above, we'll use FastAPI as the backend framework. The application pattern will feel natural if you're familiar with Flask.

FastAPI has quickly become a go-to framework for setting up APIs for data science and analytics-based workloads. From the project page:

FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+ based on standard Python type hints.

Among some of the callouts:

Fast: Very high performance, on par with NodeJS and Go
Robust: Get production-ready code. With automatic interactive documentation.

This is a great option for data science teams that want to focus on productionalizing APIs with the ability to scale in the future if needed.

Also, as we'll see below, testing locally is a smooth process using Docker.

Serverless containers with Amplify

If you need an escape hatch from just using Lambda then this may be a great option for you. We'll walk through a more basic set up below but the same approach can be leveraged for more complex backends using a docker-compose.yml configuration.

Serverless containers provide the ability for you to deploy APIs and host websites using AWS Fargate. Customers with existing applications or those who require a lower level of control can bring Docker containers and deploy them into an Amplify project fully integrating with other resources.

Project set up

Okay, let's deploy an API.

First, create a new directory and initialize the the Amplify project. In this example, I'm not hooking up a frontend so I just select the default options. But, if a frontend is something that you're interested in, then it's possible to layer that on and have the UI (React, Vue, etc.) talk to the backend API that is being created.

Make the directory.

 mkdir fastapi-amplify

Initialize the Amplify project.

amplify init

Terminal workflow

Scanning for plugins...
Plugin scan successful
Note: It is recommended to run this command from the root of your app directory
? Enter a name for the project fastapiamplify
? Enter a name for the environment dev
? Choose your default editor: Visual Studio Code
? Choose the type of app that you're building javascript
Please tell us about your project
? What javascript framework are you using none
? Source Directory Path:  src
? Distribution Directory Path: dist
? Build Command:  npm run-script build
? Start Command: npm run-script start

Enabling container-based deployments

Now, with the project initialized, we need to enable the use of the container-based deployment options.

amplify configure project

Terminal workflow

? Which setting do you want to configure? Advanced: Container-based deployments
Using default provider  awscloudformation
? Do you want to enable container-based deployments? Yes

Adding the API

With the project configured, let's add the soon-to-be API.

amplify add api

Terminal workflow

? Please select from one of the below mentioned services: REST
? Which service would you like to use API Gateway + AWS Fargate (Container-based)
? Provide a friendly name for your resource to be used as a label for this category in the project: fastapirest
? What image would you like to use Custom (bring your own Dockerfile or docker-compose.yml)
? When do you want to build & deploy the Fargate task On every "amplify push" (Fully managed container source)
? Do you want to restrict API access No
Successfully added resource fastapirest locally.

The CLI will output some next steps for setting up the API to use a bring-your-own-container setup.

Next steps:
- Place your Dockerfile, docker-compose.yml and any related container source files in "amplify/backend/api/fastapirest/src"
- Amplify CLI infers many configuration settings from the "docker-compose.yaml" file. Learn more: docs.amplify.aws/cli/usage/containers
- Run "amplify push" to build and deploy your image

Following the above steps, the following app/ and Dockerfile are added to the API directory in the Amplify backend.

  .
  ├── amplify/backend/api/<api-name>/src/
+ │   └── app
+ │       └── main.py
+ └────── Dockerfile

Adding the Dockerfile

This can be modified based on the needs and requirements of the project but the below default Dockerfile will get you up-and-running immediately with FastAPI.

I've adjusted the example in the FastAPI docs to use python3.8 instead of python3.7 and added the statement to expose port 80.

# Dockerfile
FROM tiangolo/uvicorn-gunicorn-fastapi:python3.8

# for Amplify 
# https://docs.amplify.aws/cli/usage/containers#deploy-a-single-container
EXPOSE 80

COPY ./app /app

Make sure to add EXPOSE 80 to specify a port to communicate with the container. Amplify will suggest to use port 80 if you don't provide one.

Setting up the API

Now, we can add in the API logic in the main.py file within app/.

# main.py

from typing import Optional
from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"Hello": "World"}


@app.get("/items/{item_id}")
def read_item(item_id: int, q: Optional[str] = None):
    return {"item_id": item_id, "q": q}

Testing locally

With everything in place, we can test the API using Docker. Jump into the backend API directory (i.e. where the Dockerfile is) and build the image.

cd amplify/backend/api/<api-name>/src/

Build the image.

docker build -t fastapi .

Now, you can run the image locally, exposed on port 80 of your localhost setup.

docker run -d --name fastapi -p 80:80 fastapi

You'll see the auto-generated API documentation at http://127.0.0.1/redoc or http://127.0.0.1/docs.

Deploying to Amplify 🚀

Awesome! Now let's push this to Amplify.

amplify push

When prompted, select Yes to Create the new resource.

(🚀 dev) 🐶 ➜  fastapi-amplify amplify push                                                                                  (main) ✗
✔ Successfully pulled backend environment dev from the cloud.

Current Environment: dev

| Category | Resource name | Operation | Provider plugin   |
| -------- | ------------- | --------- | ----------------- |
| Api      | fastapirest   | Create    | awscloudformation |
? Are you sure you want to continue? Yes

After the process is complete. 👇

✔ All resources are updated in the cloud

REST API endpoint: https://<id>.execute-api.<region>.amazonaws.com

Testing the deployed API

After being deployed, the API can be accessed using the endpoint above:

Also, the live API documentation is live at the https://<endpoint>/docs and https://<endpoint>/redoc.

`/docs` route

`/redoc` route

This is just scratching the surface of configuration options. Hope this helps you get running quickly with serverless FastAPI backends!

Subscribe to get my latest content by email -> Newsletter

Displaying the active Amplify Environment alongside the current Git branch

siegerts — Mon, 10 May 2021 16:50:10 +0000

Working with a lot of Git branches can get a bit tricky when they align to different Amplify environments. I usually find myself checking amplify status or amplify env list to determine the active environment. Below is an approach that is a bit more dynamic and similar to what Git and Python virtual environments show while working in the terminal.

Prerequisites

You'll need to have the below installed for the function to take effect.

git - used to determine the root directory of your Amplify project
jq - helps with parsing JSON
oh-my-zsh - managing terminal functions and themes

Display the active Amplify `env`

Add the below into your .zshrc or .bashrc. The output of the function can be adjusted depending on how you'd like to display the information. I display mine to the left of the current working directory by adjusting my zsh custom theme (below). This puts the environment name in a similar spot to where an active Python virtual environment name will show.

# .zshrc

amplify_env () {
    PROJECT_DIR=$(git rev-parse --show-toplevel 2>/dev/null) 

    ENV=$PROJECT_DIR/amplify/.config/local-env-info.json 

    if [ -f "$ENV" ]; then
        env_info=$(cat $ENV | jq -r ".envName") 
        echo "(🚀 $env_info)"
    fi
}

The function checks for the current working environment name in the <project>/amplify/.config/local-env-info.json file. This approach requires a few extra steps but is quicker than re-computing on each terminal input using the amplify status CLI command.

After re-sourcing your .zshrc (below), the environment function can be invoked by running amplify_env in the terminal.

source ~/.zshrc

Adding to a custom theme

If you're using oh-my-zsh, then you can adjust your theme (or any theme) to add the output of the function so that it shows in the terminal prompts. The updated PROMPT below now includes the Amplify environment function output (${amplify_env}).

# ~/.oh-my-zsh/custom/themes/<my-custom-theme>.zsh-theme

- PROMPT='${ret_status} %{$fg[cyan]%}%c%{$reset_color%} '
+ PROMPT='$(amplify_env) ${ret_status} %{$fg[cyan]%}%c%{$reset_color%} '
...

Amplify `env` + Git branch = 🔥

Now the environment is displayed alongside the Git branch that is active. This is a nice way to quickly determine if I need to switch branches or environments to match. Make sure to initialize Git in the project(git init) if the environment name and the Git branch aren't showing.

Hopefully that helps keep your Amplify environments visually in sync with your current Git branch 🌲.