mirror of
https://github.com/streamyfin/streamyfin.git
synced 2026-02-18 18:12:23 +00:00
956eea8848
Strengthens code quality guidelines by establishing strict TypeScript practices that prohibit `any` types and minimize type suppressions. Updates Copilot instructions to emphasize production-ready code with comprehensive type safety rules, error handling requirements, and reliability standards. Explicitly discourages type escape hatches in favor of proper type definitions. Refactors navigation implementation to use URLSearchParams instead of object-based params, eliminating the need for type suppression while maintaining functionality. Removes unnecessary type error suppressions and unused properties throughout codebase, aligning with new standards.
126 lines
5.1 KiB
Markdown
126 lines
5.1 KiB
Markdown
# Copilot Instructions for Streamyfin
|
||
|
||
## Project Overview
|
||
|
||
Streamyfin is a cross-platform Jellyfin video streaming client built with Expo (React Native).
|
||
It supports mobile (iOS/Android) and TV platforms, integrates with Jellyfin and Seerr APIs,
|
||
and provides seamless media streaming with offline capabilities and Chromecast support.
|
||
|
||
## Main Technologies
|
||
|
||
- **Runtime**: Bun (JavaScript/TypeScript execution)
|
||
- **Framework**: React Native (Expo)
|
||
- **Language**: TypeScript (strict mode)
|
||
- **State Management**: Jotai (global state) + React Query (server state)
|
||
- **API SDK**: Jellyfin SDK (TypeScript)
|
||
- **Navigation**: Expo Router (file-based routing)
|
||
- **Code Quality**: BiomeJS (formatting/linting)
|
||
- **Build Platform**: EAS (Expo Application Services)
|
||
- **CI/CD**: GitHub Actions with Bun
|
||
|
||
## Package Management
|
||
|
||
**CRITICAL: ALWAYS use `bun` for all package management operations**
|
||
|
||
- **NEVER use `npm`, `yarn` or `npx` commands**
|
||
- Use `bun install` instead of `npm install` or `yarn install`
|
||
- Use `bun add <package>` instead of `npm install <package>`
|
||
- Use `bun remove <package>` instead of `npm uninstall <package>`
|
||
- Use `bun run <script>` instead of `npm run <script>`
|
||
- Use `bunx <command>` instead of `npx <command>`
|
||
- For Expo: use `bunx create-expo-app` or `bunx @expo/cli`
|
||
|
||
## Code Structure
|
||
|
||
- `app/` – Main application code (screens, navigation, etc.)
|
||
- `components/` – Reusable UI components
|
||
- `providers/` – Context and API providers (e.g., JellyfinProvider.tsx)
|
||
- `utils/` – Utility functions and Jotai atoms
|
||
- `assets/` – Images and static assets
|
||
- `scripts/` – Automation scripts (Node.js, Bash)
|
||
- `plugins/` – Expo/Metro plugins
|
||
|
||
## Code Quality Standards
|
||
|
||
**CRITICAL: Code must be production-ready, reliable, and maintainable**
|
||
|
||
### Type Safety
|
||
- Use TypeScript for ALL files (no .js files)
|
||
- **NEVER use `any` type** - use proper types, generics, or `unknown` with type guards
|
||
- Use `@ts-expect-error` with detailed comments only when necessary (e.g., library limitations)
|
||
- When facing type issues, create proper type definitions and helper functions instead of using `any`
|
||
- Use type assertions (`as`) only as a last resort with clear documentation explaining why
|
||
- For Expo Router navigation: prefer string URLs with `URLSearchParams` over object syntax to avoid type conflicts
|
||
- Enable and respect strict TypeScript compiler options
|
||
- Define explicit return types for functions
|
||
- Use discriminated unions for complex state
|
||
|
||
### Code Reliability
|
||
- Implement comprehensive error handling with try-catch blocks
|
||
- Validate all external inputs (API responses, user input, query params)
|
||
- Handle edge cases explicitly (empty arrays, null, undefined)
|
||
- Use optional chaining (`?.`) and nullish coalescing (`??`) appropriately
|
||
- Add runtime checks for critical operations
|
||
- Implement proper loading and error states in components
|
||
|
||
### Best Practices
|
||
- Use descriptive English names for variables, functions, and components
|
||
- Prefer functional React components with hooks
|
||
- Use Jotai atoms for global state management
|
||
- Use React Query for server state and caching
|
||
- Follow BiomeJS formatting and linting rules
|
||
- Use `const` over `let`, avoid `var` entirely
|
||
- Implement proper error boundaries
|
||
- Use React.memo() for performance optimization when needed
|
||
- Handle both mobile and TV navigation patterns
|
||
- Write self-documenting code with clear intent
|
||
- Add comments only when code complexity requires explanation
|
||
|
||
## API Integration
|
||
|
||
- Use Jellyfin SDK for all server interactions
|
||
- Access authenticated APIs via `apiAtom` and `userAtom` from JellyfinProvider
|
||
- Implement proper loading states and error handling
|
||
- Use React Query for caching and background updates
|
||
- Handle offline scenarios gracefully
|
||
|
||
## Performance Optimization
|
||
|
||
- Leverage Bun's superior runtime performance
|
||
- Optimize FlatList components with proper props
|
||
- Use lazy loading for non-critical components
|
||
- Implement proper image caching strategies
|
||
- Monitor bundle size and use tree-shaking effectively
|
||
|
||
## Testing
|
||
|
||
- Use Bun's built-in test runner when possible
|
||
- Test files: `*.test.ts` or `*.test.tsx`
|
||
- Run tests with: `bun test`
|
||
- Mock external APIs in tests
|
||
- Focus on testing business logic and custom hooks
|
||
|
||
## Commit Messages
|
||
|
||
Use Conventional Commits (https://www.conventionalcommits.org/):
|
||
Exemples:
|
||
- `feat(player): add Chromecast support`
|
||
- `fix(auth): handle expired JWT tokens`
|
||
- `chore(deps): update Jellyfin SDK`
|
||
|
||
## Internationalization (i18n)
|
||
|
||
- **ONLY edit `translations/en.json` for translation changes**
|
||
- **NEVER modify other translation files** (ar.json, ca.json, cs.json, de.json, etc.)
|
||
- Crowdin automatically handles translations for all other languages
|
||
- All translation keys must be added to `en.json` first, then Crowdin syncs them
|
||
|
||
## Special Instructions
|
||
|
||
- Prioritize cross-platform compatibility (mobile + TV)
|
||
- Ensure accessibility for TV remote navigation
|
||
- Use existing atoms, hooks, and utilities before creating new ones
|
||
- Maintain compatibility with Expo and EAS workflows
|
||
- Always verify Bun compatibility when suggesting new dependencies
|
||
|
||
**Copilot: Please use these instructions to provide context-aware suggestions and code completions for this repository.** |