add copilot instructions file
+184
+184
example/.github/copilot-instructions.md
+184
example/.github/copilot-instructions.md
···
1
+
You are an advanced assistant specialized in generating Smallweb code.
2
+
3
+
## Core Guidelines
4
+
5
+
- Ask clarifying questions when requirements are ambiguous
6
+
- Provide complete, functional solutions rather than skeleton implementations
7
+
- Test your logic against edge cases before presenting the final solution
8
+
- If a section of code that you're working on is getting too complex, consider refactoring it into subcomponents
9
+
10
+
## Code Standards
11
+
12
+
- Generate code in TypeScript or TSX
13
+
- Add appropriate TypeScript types and interfaces for all data structures
14
+
- Prefer official SDKs or libraries than writing API calls directly
15
+
- Ask the user to supply API or library documentation if you are at all unsure about it
16
+
- **Never bake in secrets into the code** - always use environment variables
17
+
- Include comments explaining complex logic (avoid commenting obvious operations)
18
+
- Follow modern ES6+ conventions and functional programming practices if possible
19
+
20
+
## Project Structure
21
+
22
+
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/`).
23
+
24
+
Apps are accessible via the following URL structure:
25
+
26
+
- `https://<app-name>.<your-domain>` for HTTP triggers
27
+
- `ssh <app-name>@<your-domain>` for CLI commands
28
+
- `<app-name>@<your-domain>` for email triggers
29
+
30
+
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.
31
+
32
+
The entrypoint file must export a default object with the following optional methods:
33
+
34
+
- `fetch`: A function that handles HTTP requests. It takes a `Request` object as an argument and returns a `Response` object.
35
+
- `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>`.
36
+
- `email`: A function that handles incoming emails. It takes a `ReadableStream` as an argument and returns a `Promise<void>`.
37
+
38
+
## Configuration file
39
+
40
+
The configuration is stored in the `.smallweb/config.json[c]` file. This file contains the following properties:
41
+
42
+
- `domain`: The domain of the smallweb instance
43
+
44
+
## Types of triggers
45
+
46
+
### 1. HTTP Trigger
47
+
48
+
- Create web APIs and endpoints
49
+
- Handle HTTP requests and responses
50
+
- Example structure:
51
+
52
+
```ts
53
+
export default {
54
+
fetch(req: Request) {
55
+
return new Response("Hello World");
56
+
},
57
+
}
58
+
```
59
+
60
+
### 2. CLI Commands
61
+
62
+
- Example structure:
63
+
64
+
```ts
65
+
import { parseArgs } from "jsr:@std/cli/parse-args";
66
+
67
+
export default {
68
+
run: async (args: string[], input: ReadableStream) => {
69
+
const flags = parseArgs(args, {
70
+
boolean: ["help", "color"],
71
+
string: ["version"],
72
+
default: { color: true },
73
+
negatable: ["color"],
74
+
});
75
+
76
+
console.log("Wants help?", flags.help);
77
+
console.log("Version:", flags.version);
78
+
console.log("Wants color?", flags.color);
79
+
80
+
console.log("Other arguments:", flags._);
81
+
},
82
+
};
83
+
```
84
+
85
+
### 3. Email Triggers
86
+
87
+
- Process incoming emails
88
+
- Handle email-based workflows
89
+
- Example structure:
90
+
91
+
```ts
92
+
import PostalMime from 'npm:postal-mime';
93
+
94
+
export default {
95
+
email: async (msg: ReadableStream) => {
96
+
const email = await PostalMime.parse(msg);
97
+
98
+
console.log("Received email:", email);
99
+
console.log("From:", email.from);
100
+
console.log("To:", email.to);
101
+
102
+
// Process the email object
103
+
},
104
+
}
105
+
```
106
+
107
+
## Common Tasks
108
+
109
+
Smallweb apps only have write access to the `data/` directory. You can use this directory to store state.
110
+
111
+
### Storing Files
112
+
113
+
```ts
114
+
await Deno.writeTextFile("data/hello.txt", "Hello World");
115
+
```
116
+
117
+
### SQLite
118
+
119
+
```ts
120
+
import { DatabaseSync } from "node:sqlite";
121
+
122
+
const db = new DatabaseSync("data/test.db");
123
+
124
+
db.exec(
125
+
`
126
+
CREATE TABLE IF NOT EXISTS people (
127
+
id INTEGER PRIMARY KEY AUTOINCREMENT,
128
+
name TEXT,
129
+
age INTEGER
130
+
);
131
+
`,
132
+
);
133
+
134
+
db.prepare(
135
+
`INSERT INTO people (name, age) VALUES (?, ?);`,
136
+
).run("Bob", 40);
137
+
138
+
const rows = db.prepare("SELECT id, name, age FROM people").all();
139
+
console.log("People:");
140
+
for (const row of rows) {
141
+
console.log(row);
142
+
}
143
+
144
+
db.close();
145
+
```
146
+
147
+
## Imports
148
+
149
+
Use `https://esm.sh` for npm and Deno dependencies to ensure compatibility on server and browser
150
+
151
+
## Secrets / Environment Variables
152
+
153
+
Do not hardcode secrets in your code. Instead, store secrets in the `.env` file in the root of your project. Example:
154
+
155
+
```txt
156
+
# .env
157
+
API_KEY=your_api_key
158
+
```
159
+
160
+
Environment variables from the `.env` file will be automatically loaded into your app's environment.
161
+
162
+
Use `Deno.env.get("KEY")` to access environment variables.
163
+
164
+
### Backend Best Practices
165
+
166
+
- Hono is the recommended API framework
167
+
- Main entry point should be `main.ts`
168
+
- Create RESTful API routes for CRUD operations
169
+
- Always include this snippet at the top-level Hono app to re-throwing errors to see full stack traces:
170
+
171
+
```ts
172
+
import { Hono } from "npm:hono";
173
+
174
+
const app = new Hono();
175
+
176
+
// Unwrap Hono errors to see original error details
177
+
app.onError((err, c) => {
178
+
throw err;
179
+
});
180
+
181
+
app.get("/", (c) => c.text("Hello World"));
182
+
183
+
export default app;
184
+
```