Skip to content

tsconfig placed in quickstart.md #143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
godronus merged 3 commits into from
Jun 15, 2026
+62 −30
Merged

tsconfig placed in quickstart.md #143

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
078cef6
tsconfig placed in quickstart.md
godronus Jun 15, 2026
7c9e582
fix for tsconfig
godronus Jun 15, 2026
2b3655d
tsconfig fixes
godronus Jun 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 23 additions & 23 deletions docs/INDEX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,16 +76,16 @@ imports are resolved at compile time by the SDK.

### KvStoreInstance Methods

| Method | Signature | Description |
| ---------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `get` | `(key: string): ArrayBuffer \| null` | Retrieve a value by key |
| `getEntry` | `(key: string): Promise<KvStoreEntry \| null>` | Retrieve a value as a `KvStoreEntry` |
| `scan` | `(pattern: string): Array<string>` | Retrieve keys matching a prefix pattern (e.g. `foo*`) |
| `zrangeByScore` | `(key: string, min: number, max: number): Array<[ArrayBuffer, number]>` | Retrieve sorted set entries by score range |
| `zrangeByScoreEntries` | `(key: string, min: number, max: number): Promise<Array<[KvStoreEntry, number]>>` | `zrangeByScore` returning `KvStoreEntry` wrappers |
| `zscan` | `(key: string, pattern: string): Array<[ArrayBuffer, number]>` | Retrieve sorted set entries matching a prefix pattern |
| `zscanEntries` | `(key: string, pattern: string): Promise<Array<[KvStoreEntry, number]>>` | `zscan` returning `KvStoreEntry` wrappers |
| `bfExists` | `(key: string, value: string): boolean` | Check if a value exists in a Bloom Filter |
| Method | Signature | Description |
| ---------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `get` | `(key: string): ArrayBuffer \| null` | Retrieve a value by key |
| `getEntry` | `(key: string): Promise<KvStoreEntry \| null>` | Retrieve a value as a `KvStoreEntry` |
| `scan` | `(pattern: string): Array<string>` | Retrieve keys matching a prefix pattern (e.g. `foo*`) |
| `zrangeByScore` | `(key: string, min: number, max: number): Array<[ArrayBuffer, number]>` | Retrieve sorted set entries by score range |
| `zrangeByScoreEntries` | `(key: string, min: number, max: number): Promise<Array<[KvStoreEntry, number]>>` | `zrangeByScore` returning `KvStoreEntry` wrappers |
| `zscan` | `(key: string, pattern: string): Array<[ArrayBuffer, number]>` | Retrieve sorted set entries matching a prefix pattern |
| `zscanEntries` | `(key: string, pattern: string): Promise<Array<[KvStoreEntry, number]>>` | `zscan` returning `KvStoreEntry` wrappers |
| `bfExists` | `(key: string, value: string): boolean` | Check if a value exists in a Bloom Filter |

### KvStoreEntry Methods

Expand Down Expand Up @@ -127,19 +127,19 @@ async function app(event) {
addEventListener('fetch', (event) => event.respondWith(app(event)));
```

| Method | Signature | Description |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `get` | `(key: string): Promise<CacheEntry \| null>` | Get entry or `null` if absent or expired |
| `exists` | `(key: string): Promise<boolean>` | Check key presence without transferring value |
| `set` | `(key: string, value: CacheValue, options?: WriteOptions): Promise<void>` | Store a value, optionally with expiry |
| `delete` | `(key: string): Promise<void>` | Remove a key; no-op if absent |
| `expire` | `(key: string, options: WriteOptions): Promise<boolean>` | Update expiry; `true` if key exists, `false` if not |
| `incr` | `(key: string, delta?: number): Promise<number>` | Atomically increment an integer; returns new value |
| `decr` | `(key: string, delta?: number): Promise<number>` | Atomically decrement an integer; returns new value |
| `getOrSet` | `(key: string, populate: () => CacheValue \| Promise<CacheValue>, options?: WriteOptions): Promise<CacheEntry>` | Get entry or populate, cache, and return the result |
| `getOrSet` | `(key: string, populate: () => CacheValue \| null \| Promise<CacheValue \| null>, options?: WriteOptions): Promise<CacheEntry \| null>` | As above; a `null` populator result skips the write and resolves with `null` |
| `purge` | `(): Promise<number>` | Delete all cache entries for this application; returns count deleted |
| `purgePrefix` | `(prefix: string): Promise<number>` | Delete all entries whose keys begin with `prefix`; returns count deleted |
| Method | Signature | Description |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `get` | `(key: string): Promise<CacheEntry \| null>` | Get entry or `null` if absent or expired |
| `exists` | `(key: string): Promise<boolean>` | Check key presence without transferring value |
| `set` | `(key: string, value: CacheValue, options?: WriteOptions): Promise<void>` | Store a value, optionally with expiry |
| `delete` | `(key: string): Promise<void>` | Remove a key; no-op if absent |
| `expire` | `(key: string, options: WriteOptions): Promise<boolean>` | Update expiry; `true` if key exists, `false` if not |
| `incr` | `(key: string, delta?: number): Promise<number>` | Atomically increment an integer; returns new value |
| `decr` | `(key: string, delta?: number): Promise<number>` | Atomically decrement an integer; returns new value |
| `getOrSet` | `(key: string, populate: () => CacheValue \| Promise<CacheValue>, options?: WriteOptions): Promise<CacheEntry>` | Get entry or populate, cache, and return the result |
| `getOrSet` | `(key: string, populate: () => CacheValue \| null \| Promise<CacheValue \| null>, options?: WriteOptions): Promise<CacheEntry \| null>` | As above; a `null` populator result skips the write and resolves with `null` |
| `purge` | `(): Promise<number>` | Delete all cache entries for this application; returns count deleted |
| `purgePrefix` | `(prefix: string): Promise<number>` | Delete all entries whose keys begin with `prefix`; returns count deleted |

### CacheValue

Expand Down
31 changes: 27 additions & 4 deletions docs/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,33 @@ npx fastedge-build --input src/index.ts --output app.wasm --tsconfig tsconfig.js
| `--version` | `-v` | `boolean` | Print version |
| `--help` | `-h` | `boolean` | Print help |

## TypeScript Configuration

If you're using TypeScript, use a `tsconfig.json` that works with `fastedge-build`'s esbuild-based compilation pipeline. The following is the canonical template:

```json
{
"compilerOptions": {
"target": "ES2023",
"module": "ESNext",
"moduleResolution": "Bundler",
"strict": true,
"skipLibCheck": true,
"noEmit": true,
"lib": ["ES2023"],
"types": ["@gcoredev/fastedge-sdk-js"]
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
```

Three settings require explanation:

- **`moduleResolution: "Bundler"`** — Required. `fastedge-build` uses esbuild to resolve modules, not Node's resolution algorithm. The `node`, `node16`, and `nodenext` modes are incorrect for FastEdge apps and will produce spurious import errors.
- **`types: ["@gcoredev/fastedge-sdk-js"]`** — Brings `FetchEvent` and all FastEdge globals into scope automatically. No triple-slash directive (`/// <reference types="..." />`) is needed in TypeScript source files when this field is set.
- **`noEmit: true`** — `tsc` is used for type-checking only. `fastedge-build` handles the actual compilation to WebAssembly; emitting JavaScript from `tsc` would be redundant and incorrect.

## Write Your First App

Create `src/index.js`:
Expand Down Expand Up @@ -91,7 +118,6 @@ The output `app.wasm` is a WebAssembly component ready for deployment on the Fas
`getEnv` is only available during request processing, not at build-time initialization.

```js
/// <reference types="@gcoredev/fastedge-sdk-js" />
import { getEnv } from 'fastedge::env';

addEventListener('fetch', (event) => {
Expand All @@ -116,7 +142,6 @@ Returns `null` when the environment variable is not set.
`getSecret` and `getSecretEffectiveAt` are only available during request processing, not at build-time initialization.

```js
/// <reference types="@gcoredev/fastedge-sdk-js" />
import { getSecret } from 'fastedge::secret';

addEventListener('fetch', (event) => {
Expand All @@ -140,7 +165,6 @@ Both return `null` when the secret is not set.
## Using KV Store

```js
/// <reference types="@gcoredev/fastedge-sdk-js" />
import { KvStore } from 'fastedge::kv';

addEventListener('fetch', (event) => {
Expand Down Expand Up @@ -182,7 +206,6 @@ addEventListener('fetch', (event) => {
The `fastedge::cache` module provides a POP-local key/value store with TTL and atomic counter primitives. Unlike `fastedge::kv`, which is globally replicated across all data centers, the cache is strongly consistent within a single point of presence and invisible to other POPs — making it suited for request-time state such as rate limiting, hit counters, and response memoisation where low latency within a POP matters more than global durability.

```js
/// <reference types="@gcoredev/fastedge-sdk-js" />
import { Cache } from 'fastedge::cache';

addEventListener('fetch', (event) => {
Expand Down
13 changes: 11 additions & 2 deletions fastedge-plugin-source/.generation-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,13 +80,22 @@ files:** `package.json`, `README.md` **Required content:**
## docs/quickstart.md

**Scope:** First-time setup — install, scaffold, build, deploy **Source files:** `package.json`,
`README.md`, `src/cli/fastedge-init/init.ts`, `src/cli/fastedge-build/build.ts` **Required
content:**
`README.md`, `src/cli/fastedge-init/init.ts`, `src/cli/fastedge-build/build.ts`,
`examples/cache/tsconfig.json` **Required content:**

- Prerequisites — read the minimum Node version from `package.json` `engines.node` field (do NOT
hardcode a version number)
- npm install command
- Two paths: scaffold with fastedge-init OR build directly
- **TypeScript Configuration** — a dedicated section explaining the canonical `tsconfig.json` for
FastEdge apps. Include the full JSON block verbatim from `examples/cache/tsconfig.json` (that file
is the authoritative app-level template; do NOT use the repo-root `tsconfig.json`, which is the
SDK's own build config). Briefly explain the three non-obvious settings: `moduleResolution:
"Bundler"` (required — esbuild handles resolution, not Node), `types:
["@gcoredev/fastedge-sdk-js"]` (brings `FetchEvent` and all FastEdge globals into scope without a
triple-slash directive), `noEmit: true` (tsc is used for type-checking only; `fastedge-build`
handles the actual compilation). Note that `node`, `node16`, and `nodenext` moduleResolution modes
are incorrect for FastEdge apps and will produce spurious errors.
- Complete "first app" example with env vars, secrets, and KV store
- Short "Using Cache" section after "Using KV Store" — one paragraph contrasting POP-local Cache vs
globally-replicated KV, plus a minimal example covering `Cache.get`/`Cache.set` (or
Expand Down
2 changes: 1 addition & 1 deletion fastedge-plugin-source/generate-docs.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ ALL_FILES=("${TIER1_FILES[@]}" "${TIER2_FILES[@]}" "${TIER3_FILES[@]}")

declare -A SOURCE_FILES
SOURCE_FILES[INDEX.md]="package.json README.md docs/SDK_API.md"
SOURCE_FILES[quickstart.md]="README.md src/cli/fastedge-init/init.ts src/cli/fastedge-build/build.ts"
SOURCE_FILES[quickstart.md]="README.md src/cli/fastedge-init/init.ts src/cli/fastedge-build/build.ts examples/cache/tsconfig.json"
SOURCE_FILES[BUILD_CLI.md]="src/cli/fastedge-build/build.ts src/cli/fastedge-build/types.ts src/cli/fastedge-build/config-build.ts"
SOURCE_FILES[INIT_CLI.md]="src/cli/fastedge-init/init.ts src/cli/fastedge-init/http-handler.ts src/cli/fastedge-init/static-site.ts src/cli/fastedge-init/create-config.ts"
SOURCE_FILES[ASSETS_CLI.md]="src/cli/fastedge-assets/asset-cli.ts src/server/static-assets/asset-manifest/create-manifest.ts"
Expand Down
Loading