General.mdc

description: globs: alwaysApply: false

description: General TypeScript coding guidelines globs:

General

Write elegant, concise, and readable code
Prefer
```
const
```
over
```
let
```
(never use
```
var
```
)
Use kebab-case for file and directory names
Use clear, descriptive names for variables, functions, and components

Modules

Imports & Exports

Always use ESM

import

and

export

(never use CJS

require

)

File imports should never use an extension (NOT
```
.js
```
,
```
.ts
```
or
```
.tsx
```
).

GOOD examples:

```
import { Foo } from './foo'
```

import { type Route } from './types/root'

```
import zod from 'zod'
```
```
import { logger } from '~/types'
```

BAD examples:

```
import { Foo } from './foo.js'
```

import { type Route } from './types/root.js'

```
import { Foo } from './foo.ts'
```

Always prefer named exports over default exports

Packages

All packages must follow these

package.json

rules:

```
type
```
must be set to
```
module
```

TypeScript

Avoid semicolons at the end of lines
Use TypeScript's utility types (e.g.,
```
Partial
```
,
```
Pick
```
,
```
Omit
```
) to manipulate existing types
Create custom types for complex data structures used throughout the application
If possible, avoid using
```
any
```
/
```
unknown
```
or casting values like
```
(value as any)
```
in TypeScript outside of test files e.g.
```
*.test.ts
```
or test fixtures e.g.
```
**/test-data.ts
```
.
Don't rely on
```
typeof
```
,
```
ReturnType<>
```
,
```
Awaited<>
```
, etc for complex type inference (it's ok for simple types)
You can use
```
as const
```
as needed for better type inference

Functions should accept an object parameter instead of multiple parameters

Good examples:

function myFunction({ foo, bar }: { foo: boolean; bar: string }) {}
function VideoPlayer({ sid }: { sid: string }) {}

Bad examples:

function myFunction(foo: boolean, bar: string, baz: number) {}

Arguments should generally be destructured in the function definition, not the function body.

Good example:

function myFunction({ foo, bar }: { foo: boolean; bar: string }) {}

Bad example:

function myFunction(args: { foo: boolean; bar: string }) {
  const { foo, bar } = args
}

Zod should be used to parse untrusted data, but not for data that is trusted like function arguments

Prefer Zod unions over Zod enums

For example, this union

z.union([ z.literal('youtube'), z.literal('spotify') ])

is better than this enum

z.enum([ 'youtube', 'spotify' ])

Promises (and
```
async
```
functions which implicitly create Promises) must always be properly handled, either via:
- Using
```
await
```
  to wait for the Promise to resolve successfully
- Using
```
.then
```
  or
```
.catch
```
  to handle Promise resolution
- Returning a Promise to a calling function which itself has to handle the Promise.

Node.js

Utilize the
```
node:
```
protocol when importing Node.js modules (e.g.,
```
import fs from 'node:fs/promises'
```
)
Prefer promise-based APIs over Node's legacy callback APIs
Use environment variables for secrets (avoid hardcoding sensitive information)

Web Standard APIs

Always prefer using standard web APIs like

fetch

WebSocket

, and

ReadableStream

when possible. Avoid redundant libraries (like

node-fetch

Prefer the
```
fetch
```
API for making HTTP requests instead of Node.js modules like
```
http
```
or
```
https
```
- Use the native
```
fetch
```
  API instead of
```
node-fetch
```
  or polyfilled
```
cross-fetch
```
- Use the
```
ky
```
  library for HTTP requests instead of
```
axios
```
  or
```
superagent
```
Use the WHATWG
```
URL
```
and
```
URLSearchParams
```
classes instead of the Node.js
```
url
```
module
Use
```
Request
```
and
```
Response
```
objects from the Fetch API instead of Node.js-specific request and response objects

Error Handling

Prefer
```
async
```
/
```
await
```
over
```
.then()
```
and
```
.catch()
```
Always handle errors correctly (eg:
```
try
```
/
```
catch
```
or
```
.catch()
```
)
Avoid swallowing errors silently; always log or handle caught errors appropriately

Comments

Comments should be used to document and explain code. They should complement the use of descriptive variable and function names and type declarations.

Add comments to explain complex sections of code
Add comments that will improve the autocompletion preview in IDEs (eg: functions and types)
Don't add comments that just reword symbol names or repeat type declarations
Use JSDoc formatting for comments (not TSDoc or inline comments)

Logging

Just use
```
console
```
for logging.

Testing

Unit Testing

All unit tests should use Vitest
- DO NOT attempt to install or use other testing libraries like Jest
Test files should be named
```
[target].test.ts
```
and placed in the same directory as the code they are testing (NOT a separate directory)
- Good example:
```
src/my-file.ts
```
  and
```
src/my-file.test.ts
```
- Bad example:
```
src/my-file.ts
```
  and
```
src/test/my-file.test.ts
```
  or
```
test/my-file.test.ts
```
  or
```
src/__tests__/my-file.test.ts
```
Tests should be run with
```
pnpm test:unit
```
It's acceptable to use
```
any
```
/
```
unknown
```
in test files (such as
```
*.test.ts
```
) or test fixtures (like
```
**/test-data.ts
```
) to facilitate mocking or stubbing external modules or partial function arguments, referencing the usage guidelines in the TypeScript section.
Frontend react code does not need unit tests

Test Coverage

Test critical business logic and edge cases
Don't add tests for trivial code or just to increase test coverage
Don't make tests too brittle or flaky by relying on implementation details

Git

When possible, combine the
```
git add
```
and
```
git commit
```
commands into a single
```
git commit -am
```
command, to speed things up

description: globs: alwaysApply: false

description: General TypeScript coding guidelines globs:

General

Write elegant, concise, and readable code
Prefer
```
const
```
over
```
let
```
(never use
```
var
```
)
Use kebab-case for file and directory names
Use clear, descriptive names for variables, functions, and components

Modules

Imports & Exports

Always use ESM

import

and

export

(never use CJS

require

)

File imports should never use an extension (NOT
```
.js
```
,
```
.ts
```
or
```
.tsx
```
).

GOOD examples:

```
import { Foo } from './foo'
```

import { type Route } from './types/root'

```
import zod from 'zod'
```
```
import { logger } from '~/types'
```

BAD examples:

```
import { Foo } from './foo.js'
```

import { type Route } from './types/root.js'

```
import { Foo } from './foo.ts'
```

Always prefer named exports over default exports

Packages

All packages must follow these

package.json

rules:

```
type
```
must be set to
```
module
```

TypeScript

Avoid semicolons at the end of lines
Use TypeScript's utility types (e.g.,
```
Partial
```
,
```
Pick
```
,
```
Omit
```
) to manipulate existing types
Create custom types for complex data structures used throughout the application
If possible, avoid using
```
any
```
/
```
unknown
```
or casting values like
```
(value as any)
```
in TypeScript outside of test files e.g.
```
*.test.ts
```
or test fixtures e.g.
```
**/test-data.ts
```
.
Don't rely on
```
typeof
```
,
```
ReturnType<>
```
,
```
Awaited<>
```
, etc for complex type inference (it's ok for simple types)
You can use
```
as const
```
as needed for better type inference

Functions should accept an object parameter instead of multiple parameters

Good examples:

function myFunction({ foo, bar }: { foo: boolean; bar: string }) {}
function VideoPlayer({ sid }: { sid: string }) {}

Bad examples:

function myFunction(foo: boolean, bar: string, baz: number) {}

Arguments should generally be destructured in the function definition, not the function body.

Good example:

function myFunction({ foo, bar }: { foo: boolean; bar: string }) {}

Bad example:

function myFunction(args: { foo: boolean; bar: string }) {
  const { foo, bar } = args
}

Zod should be used to parse untrusted data, but not for data that is trusted like function arguments

Prefer Zod unions over Zod enums

For example, this union

z.union([ z.literal('youtube'), z.literal('spotify') ])

is better than this enum

z.enum([ 'youtube', 'spotify' ])

Promises (and
```
async
```
functions which implicitly create Promises) must always be properly handled, either via:
- Using
```
await
```
  to wait for the Promise to resolve successfully
- Using
```
.then
```
  or
```
.catch
```
  to handle Promise resolution
- Returning a Promise to a calling function which itself has to handle the Promise.

Node.js

Utilize the
```
node:
```
protocol when importing Node.js modules (e.g.,
```
import fs from 'node:fs/promises'
```
)
Prefer promise-based APIs over Node's legacy callback APIs
Use environment variables for secrets (avoid hardcoding sensitive information)

Web Standard APIs

Always prefer using standard web APIs like

fetch

WebSocket

, and

ReadableStream

when possible. Avoid redundant libraries (like

node-fetch

Prefer the
```
fetch
```
API for making HTTP requests instead of Node.js modules like
```
http
```
or
```
https
```
- Use the native
```
fetch
```
  API instead of
```
node-fetch
```
  or polyfilled
```
cross-fetch
```
- Use the
```
ky
```
  library for HTTP requests instead of
```
axios
```
  or
```
superagent
```
Use the WHATWG
```
URL
```
and
```
URLSearchParams
```
classes instead of the Node.js
```
url
```
module
Use
```
Request
```
and
```
Response
```
objects from the Fetch API instead of Node.js-specific request and response objects

Error Handling

Prefer
```
async
```
/
```
await
```
over
```
.then()
```
and
```
.catch()
```
Always handle errors correctly (eg:
```
try
```
/
```
catch
```
or
```
.catch()
```
)
Avoid swallowing errors silently; always log or handle caught errors appropriately

Comments

Comments should be used to document and explain code. They should complement the use of descriptive variable and function names and type declarations.

Add comments to explain complex sections of code
Add comments that will improve the autocompletion preview in IDEs (eg: functions and types)
Don't add comments that just reword symbol names or repeat type declarations
Use JSDoc formatting for comments (not TSDoc or inline comments)

Logging

Just use
```
console
```
for logging.

Testing

Unit Testing

All unit tests should use Vitest
- DO NOT attempt to install or use other testing libraries like Jest
Test files should be named
```
[target].test.ts
```
and placed in the same directory as the code they are testing (NOT a separate directory)
- Good example:
```
src/my-file.ts
```
  and
```
src/my-file.test.ts
```
- Bad example:
```
src/my-file.ts
```
  and
```
src/test/my-file.test.ts
```
  or
```
test/my-file.test.ts
```
  or
```
src/__tests__/my-file.test.ts
```
Tests should be run with
```
pnpm test:unit
```
It's acceptable to use
```
any
```
/
```
unknown
```
in test files (such as
```
*.test.ts
```
) or test fixtures (like
```
**/test-data.ts
```
) to facilitate mocking or stubbing external modules or partial function arguments, referencing the usage guidelines in the TypeScript section.
Frontend react code does not need unit tests

Test Coverage

Test critical business logic and edge cases
Don't add tests for trivial code or just to increase test coverage
Don't make tests too brittle or flaky by relying on implementation details

Git

When possible, combine the
```
git add
```
and
```
git commit
```
commands into a single
```
git commit -am
```
command, to speed things up

General.mdc

description: globs: alwaysApply: false

description: General TypeScript coding guidelines globs:

General

Modules

Imports & Exports

Packages

TypeScript

Node.js

Web Standard APIs

Error Handling

Comments

Logging

Testing

Unit Testing

Test Coverage

Git

Related Skills

<h1 align="center">

2. Apply Deepthink Protocol (reason about dependencies

- Identify gaps

description: globs: alwaysApply: false

description: General TypeScript coding guidelines globs:

General

Modules

Imports & Exports

Packages

TypeScript

Node.js

Web Standard APIs

Error Handling

Comments

Logging

Testing

Unit Testing

Test Coverage

Git