workspace Code Standards

This project uses Ultracite, a zero-config preset that enforces strict code quality standards through automated formatting and linting.

Quick Reference

Format code:
```
bun x ultracite fix
```
Check for issues:
```
bun x ultracite check
```
Diagnose setup:
```
bun x ultracite doctor
```

Oxlint + Oxfmt (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable.

Core Principles

Write code that is accessible, performant, type-safe, and maintainable. Focus on clarity and explicit intent over brevity.

Type Safety & Explicitness

Use explicit types for function parameters and return values when they enhance clarity
Prefer
```
unknown
```
over
```
any
```
when the type is genuinely unknown
Use const assertions (
```
as const
```
) for immutable values and literal types
Leverage TypeScript's type narrowing instead of type assertions
Use meaningful variable names instead of magic numbers - extract constants with descriptive names

Modern JavaScript/TypeScript

Use arrow functions for callbacks and short functions
Prefer
```
for...of
```
loops over
```
.forEach()
```
and indexed
```
for
```
loops
Use optional chaining (
```
?.
```
) and nullish coalescing (
```
??
```
) for safer property access
Prefer template literals over string concatenation
Use destructuring for object and array assignments
Use
```
const
```
by default,
```
let
```
only when reassignment is needed, never
```
var
```

Async & Promises

Always
```
await
```
promises in async functions - don't forget to use the return value
Use
```
async/await
```
syntax instead of promise chains for better readability
Handle errors appropriately in async code with try-catch blocks
Don't use async functions as Promise executors

React & JSX

Use function components over class components
Call hooks at the top level only, never conditionally
Specify all dependencies in hook dependency arrays correctly
Use the
```
key
```
prop for elements in iterables (prefer unique IDs over array indices)
Nest children between opening and closing tags instead of passing as props
Don't define components inside other components
Use semantic HTML and ARIA attributes for accessibility:
- Provide meaningful alt text for images
- Use proper heading hierarchy
- Add labels for form inputs
- Include keyboard event handlers alongside mouse events
- Use semantic elements (
```
<button>
```
  ,
```
<nav>
```
  , etc.) instead of divs with roles

Error Handling & Debugging

Remove
```
console.log
```
,
```
debugger
```
, and
```
alert
```
statements from production code
Throw
```
Error
```
objects with descriptive messages, not strings or other values
Use
```
try-catch
```
blocks meaningfully - don't catch errors just to rethrow them
Prefer early returns over nested conditionals for error cases

Code Organization

Keep functions focused and under reasonable cognitive complexity limits
Extract complex conditions into well-named boolean variables
Use early returns to reduce nesting
Prefer simple conditionals over nested ternary operators
Group related code together and separate concerns

Security

Add
```
rel="noopener"
```
when using
```
target="_blank"
```
on links
Avoid
```
dangerouslySetInnerHTML
```
unless absolutely necessary
Don't use
```
eval()
```
or assign directly to
```
document.cookie
```
Validate and sanitize user input

Performance

Avoid spread syntax in accumulators within loops
Use top-level regex literals instead of creating them in loops
Prefer specific imports over namespace imports
Avoid barrel files (index files that re-export everything)
Use proper image components (e.g., Next.js
```
<Image>
```
) over
```
<img>
```
tags

Framework-Specific Guidance

Next.js:

Use Next.js
```
<Image>
```
component for images
Use
```
next/head
```
or App Router metadata API for head elements
Use Server Components for async data fetching instead of async Client Components

React 19+:

Use ref as a prop instead of
```
React.forwardRef
```

Solid/Svelte/Vue/Qwik:

Use
```
class
```
and
```
for
```
attributes (not
```
className
```
or
```
htmlFor
```
)

Testing

Write assertions inside
```
it()
```
or
```
test()
```
blocks
Avoid done callbacks in async tests - use async/await instead
Don't use
```
.only
```
or
```
.skip
```
in committed code
Keep test suites reasonably flat - avoid excessive
```
describe
```
nesting

When Oxlint + Oxfmt Can't Help

Oxlint + Oxfmt's linter will catch most issues automatically. Focus your attention on:

Business logic correctness - Oxlint + Oxfmt can't validate your algorithms
Meaningful naming - Use descriptive names for functions, variables, and types
Architecture decisions - Component structure, data flow, and API design
Edge cases - Handle boundary conditions and error states
User experience - Accessibility, performance, and usability considerations
Documentation - Add comments for complex logic, but prefer self-documenting code

Most formatting and common issues are automatically fixed by Oxlint + Oxfmt. Run

bun fix

before committing to ensure compliance.

workspace Code Standards

This project uses Ultracite, a zero-config preset that enforces strict code quality standards through automated formatting and linting.

Quick Reference

Format code:
```
bun x ultracite fix
```
Check for issues:
```
bun x ultracite check
```
Diagnose setup:
```
bun x ultracite doctor
```

Oxlint + Oxfmt (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable.

Core Principles

Write code that is accessible, performant, type-safe, and maintainable. Focus on clarity and explicit intent over brevity.

Type Safety & Explicitness

Use explicit types for function parameters and return values when they enhance clarity
Prefer
```
unknown
```
over
```
any
```
when the type is genuinely unknown
Use const assertions (
```
as const
```
) for immutable values and literal types
Leverage TypeScript's type narrowing instead of type assertions
Use meaningful variable names instead of magic numbers - extract constants with descriptive names

Modern JavaScript/TypeScript

Use arrow functions for callbacks and short functions
Prefer
```
for...of
```
loops over
```
.forEach()
```
and indexed
```
for
```
loops
Use optional chaining (
```
?.
```
) and nullish coalescing (
```
??
```
) for safer property access
Prefer template literals over string concatenation
Use destructuring for object and array assignments
Use
```
const
```
by default,
```
let
```
only when reassignment is needed, never
```
var
```

Async & Promises

Always
```
await
```
promises in async functions - don't forget to use the return value
Use
```
async/await
```
syntax instead of promise chains for better readability
Handle errors appropriately in async code with try-catch blocks
Don't use async functions as Promise executors

React & JSX

Use function components over class components
Call hooks at the top level only, never conditionally
Specify all dependencies in hook dependency arrays correctly
Use the
```
key
```
prop for elements in iterables (prefer unique IDs over array indices)
Nest children between opening and closing tags instead of passing as props
Don't define components inside other components
Use semantic HTML and ARIA attributes for accessibility:
- Provide meaningful alt text for images
- Use proper heading hierarchy
- Add labels for form inputs
- Include keyboard event handlers alongside mouse events
- Use semantic elements (
```
<button>
```
  ,
```
<nav>
```
  , etc.) instead of divs with roles

Error Handling & Debugging

Remove
```
console.log
```
,
```
debugger
```
, and
```
alert
```
statements from production code
Throw
```
Error
```
objects with descriptive messages, not strings or other values
Use
```
try-catch
```
blocks meaningfully - don't catch errors just to rethrow them
Prefer early returns over nested conditionals for error cases

Code Organization

Keep functions focused and under reasonable cognitive complexity limits
Extract complex conditions into well-named boolean variables
Use early returns to reduce nesting
Prefer simple conditionals over nested ternary operators
Group related code together and separate concerns

Security

Add
```
rel="noopener"
```
when using
```
target="_blank"
```
on links
Avoid
```
dangerouslySetInnerHTML
```
unless absolutely necessary
Don't use
```
eval()
```
or assign directly to
```
document.cookie
```
Validate and sanitize user input

Performance

Avoid spread syntax in accumulators within loops
Use top-level regex literals instead of creating them in loops
Prefer specific imports over namespace imports
Avoid barrel files (index files that re-export everything)
Use proper image components (e.g., Next.js
```
<Image>
```
) over
```
<img>
```
tags

Framework-Specific Guidance

Next.js:

Use Next.js
```
<Image>
```
component for images
Use
```
next/head
```
or App Router metadata API for head elements
Use Server Components for async data fetching instead of async Client Components

React 19+:

Use ref as a prop instead of
```
React.forwardRef
```

Solid/Svelte/Vue/Qwik:

Use
```
class
```
and
```
for
```
attributes (not
```
className
```
or
```
htmlFor
```
)

Testing

Write assertions inside
```
it()
```
or
```
test()
```
blocks
Avoid done callbacks in async tests - use async/await instead
Don't use
```
.only
```
or
```
.skip
```
in committed code
Keep test suites reasonably flat - avoid excessive
```
describe
```
nesting

When Oxlint + Oxfmt Can't Help

Oxlint + Oxfmt's linter will catch most issues automatically. Focus your attention on:

Business logic correctness - Oxlint + Oxfmt can't validate your algorithms
Meaningful naming - Use descriptive names for functions, variables, and types
Architecture decisions - Component structure, data flow, and API design
Edge cases - Handle boundary conditions and error states
User experience - Accessibility, performance, and usability considerations
Documentation - Add comments for complex logic, but prefer self-documenting code

Most formatting and common issues are automatically fixed by Oxlint + Oxfmt. Run

bun fix

before committing to ensure compliance.

workspace Code Standards

workspace Code Standards

Quick Reference

Core Principles

Type Safety & Explicitness

Modern JavaScript/TypeScript

Async & Promises

React & JSX

Error Handling & Debugging

Code Organization

Security

Performance

Framework-Specific Guidance

Testing

When Oxlint + Oxfmt Can't Help

Related Skills

Markdown Converter

Nano Banana Pro

1password

workspace Code Standards

Quick Reference

Core Principles

Type Safety & Explicitness

Modern JavaScript/TypeScript

Async & Promises

React & JSX

Error Handling & Debugging

Code Organization

Security

Performance

Framework-Specific Guidance

Testing

When Oxlint + Oxfmt Can't Help