TypeScript conventions and patterns for any TypeScript code in the Phoenix monorepo — including js/packages/, app/, and any other TS directories. Use this skill whenever writing, reviewing, or modifying TypeScript code — new functions, types, exports, tests, or refactors. Also trigger when the user asks about TS patterns, naming conventions, or best practices for this project.
These conventions apply to all TypeScript in the Phoenix monorepo — the app/ frontend, the js/packages/ libraries (phoenix-client, phoenix-cli, phoenix-evals, phoenix-mcp, phoenix-otel, phoenix-config), examples, and benchmarks.
Before writing new code, explore the directory you're working in to understand existing patterns — then follow these rules.
Self-documenting names eliminate mental parsing for the next reader.
index, row, char.isAllowed, hasError, canSubmit — not allowed, error.getUser, normalizeTimestamp, , , — not , , .logEventparseResponsebuildQueryuser()timestamp()event()// Bad — single letters and ambiguous names
for (let i = 0; i < s.length; i++) {
const d = s[i].ts - s[i - 1]?.ts;
const r = fn(s[i].v);
}
// Good — self-documenting
for (let index = 0; index < spans.length; index++) {
const elapsed = spans[index].timestamp - spans[index - 1]?.timestamp;
const result = normalizeValue(spans[index].value);
}
// Bad — boolean without verb prefix, condition inline
<Button isDisabled={!permission || submitting}>
// Good — named boolean with verb prefix
const isDisabled = !hasPermission || isSubmitting;
<Button isDisabled={isDisabled}>
@param dot notation so editors surface descriptions on hover and during autocomplete.map not reduce for element-wise transforms, return new objects instead of mutating./**
* Fetch spans matching the given filters.
* @param params - query parameters
* @param params.projectId - project to query
* @param params.timeRange - optional time window to restrict results
* @param params.limit - max rows to return (default 100)
*/
function fetchSpans({
projectId,
timeRange,
limit = 100,
}: {
projectId: string;
timeRange?: TimeRange;
limit?: number;
}) {
TypeScript's type system is most valuable when it catches bugs at compile time rather than runtime.
any must not be used; prefer unknown and narrow explicitly. If any is genuinely necessary (e.g., interfacing with an untyped external API), add a comment explaining why.Record<K, V> used as a lookup map (where keys may be absent) must include undefined in the value type — the repo does not enable noUncheckedIndexedAccess, so missing-key lookups silently return undefined while the type says V. Use Partial<Record<K, V>> for sparse maps or Record<K, V | undefined> when the key set is known but values are nullable.// Bad — lookup returns string at compile time, undefined at runtime
const map: Record<string, string> = {};
const value = map["missing"]; // typed as string, actually undefined
// Good — forces a null check at every access site
const map: Partial<Record<string, string>> = {};
const value = map["missing"]; // typed as string | undefined
Existing shared utilities must be checked before writing inline helpers. Duplicated logic should be extracted to a shared module. When working in js/packages/, check sibling packages for existing utilities before adding new dependencies or reimplementing.