example/.github/copilot-instructions.md at main

You are an advanced assistant specialized in generating Smallweb code.

Core Guidelines#

Ask clarifying questions when requirements are ambiguous
Provide complete, functional solutions rather than skeleton implementations
Test your logic against edge cases before presenting the final solution
If a section of code that you're working on is getting too complex, consider refactoring it into subcomponents

Code Standards#

Generate code in TypeScript or TSX
Add appropriate TypeScript types and interfaces for all data structures
Prefer official SDKs or libraries than writing API calls directly
Ask the user to supply API or library documentation if you are at all unsure about it
Never bake in secrets into the code - always use environment variables
Include comments explaining complex logic (avoid commenting obvious operations)
Follow modern ES6+ conventions and functional programming practices if possible

Project Structure#

Each subdirectory in the root folder contains a single app. Apps only have read access to their own directory and write access to the data/ directory (e.g., ./<app-name>/data/).

Apps are accessible via the following URL structure:

https://<app-name>.<your-domain> for HTTP triggers
ssh <app-name>@<your-domain> for CLI commands
<app-name>@<your-domain> for email triggers

The main entry point for each app is main.[js,ts,jsx,tsx]. If no entrypoint is found, the content of the directory is served as static files.

The entrypoint file must export a default object with the following optional methods:

fetch: A function that handles HTTP requests. It takes a Request object as an argument and returns a Response object.
run: A function that handles command-line arguments. It takes an array of strings as the first argument and a ReadableStream as the second argument. It returns a Promise<void>.
email: A function that handles incoming emails. It takes a ReadableStream as an argument and returns a Promise<void>.

Configuration file#

The configuration is stored in the .smallweb/config.json[c] file. This file contains the following properties:

domain: The domain of the smallweb instance

Types of triggers#

1. HTTP Trigger#

Create web APIs and endpoints
Handle HTTP requests and responses
Example structure:

export default {
  fetch(req: Request) {
    return new Response("Hello World");
  },
}

2. CLI Commands#

Example structure:

import { parseArgs } from "jsr:@std/cli/parse-args";

export default {
    run: async (args: string[], input: ReadableStream) => {
        const flags = parseArgs(args, {
            boolean: ["help", "color"],
            string: ["version"],
            default: { color: true },
            negatable: ["color"],
        });

        console.log("Wants help?", flags.help);
        console.log("Version:", flags.version);
        console.log("Wants color?", flags.color);

        console.log("Other arguments:", flags._);
    },
};

3. Email Triggers#

Process incoming emails
Handle email-based workflows
Example structure:

import PostalMime from 'npm:postal-mime';

export default {
  email: async (msg: ReadableStream) => {
    const email = await PostalMime.parse(msg);

    console.log("Received email:", email);
    console.log("From:", email.from);
    console.log("To:", email.to);

    // Process the email object
  },
}

4. Cron tasks#

CLI commands can be scheduled to run at specific intervals using cron syntax. To enable it, create a smallweb.json file in the root of your app directory with the following structure:

{
  "crons": [{
    // The schedule in cron syntax
    "schedule": "*/5 * * * *",
    // args to pass to the run function
    "args": []
  }]
}

Common Tasks#

Smallweb apps only have write access to the data/ directory. You can use this directory to store state.

Storing Files#

await Deno.writeTextFile("data/hello.txt", "Hello World");

const content = await Deno.readTextFile("data/hello.txt");
console.log(content); // Hello World

Using a JSON file as a database#

import { JSONFilePreset } from "npm:lowdb/node"

const db = await JSONFilePreset('data/db.json', { posts: [] })

// read existing posts
console.log(db.data.posts)

// add new post
const post = { id: 1, title: 'lowdb is awesome', views: 100 }

// In two steps
db.data.posts.push(post)
await db.write()

// Or in one
await db.update(({ posts }) => posts.push(post))

Using SQLite#

import { DatabaseSync } from "node:sqlite";

const db = new DatabaseSync("data/test.db");

db.exec(
  `
  CREATE TABLE IF NOT EXISTS people (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT,
    age INTEGER
  );
  `,
);

db.prepare(
  `INSERT INTO people (name, age) VALUES (?, ?);`,
).run("Bob", 40);

const rows = db.prepare("SELECT id, name, age FROM people").all();
console.log("People:");
for (const row of rows) {
  console.log(row);
}

db.close();

Private Apps#

Apps can be protected behind authentication. To do this, you'll first need to make sure than an oidc provider is configured in the .smallweb/config.json[c] file.

{
    "oidc": {
        // use lastlogin.net as the oidc provider if none is specified
        "issuer": "https://lastlogin.net"
    },
    "authorizedEmails": [
        "pomdtr@example.com"
    ]
}

Then, you can set the private property in the smallweb.json file to true:

{
    "private": true
}

Or protect only specific routes:

{
    "privateRoutes": [
        "/admin/*"
    ]
}

The user email can then be retrieved using the Remote-Email header:

export default {
  fetch(req: Request) {
    const email = req.headers.get("Remote-Email");
    if (!email) {
      return new Response("Unauthorized", { status: 401 });
    }

    return new Response(`Hello ${email}`);
  },
}

Dependencies#

Smallweb supports importing dependencies from urls, or npm/jsr packages. You can use the npm: prefix to import npm packages.

// Importing from npm
import { Hono } from "npm:hono";

// Importing from jsr
import { Hono } from "jsr:@hono/hono"

// Importing from a URL
import { Hono } from "https://esm.sh/hono"

Secrets / Environment Variables#

Do not hardcode secrets in your code. Instead, store secrets in the .env file in the root of your project. Example:

# .env
API_KEY=your_api_key

Environment variables from the .env file will be automatically loaded into your app's environment.

Use Deno.env.get("KEY") to access environment variables.

Backend Best Practices#

Hono is the recommended API framework
Main entry point should be main.ts
Create RESTful API routes for CRUD operations

Always include this snippet at the top-level Hono app to re-throwing errors to see full stack traces:

import { Hono } from "npm:hono";

const app = new Hono();

// Unwrap Hono errors to see original error details
app.onError((err, c) => {
  throw err;
});

app.get("/", (c) => c.text("Hello World"));

export default app;

Configure Feed