');
expect(classes).toContain("**:text-gray-500");
});
});
```
### Integration Tests
Test with real v4 projects in `apps/test-tailwind-v4/`:
```tsx
// Test component with v4 features
export function V4TestComponent() {
return (
);
}
```
---
## Common Pitfalls & Solutions
### Pitfall 1: Wildcard `*` Conflicts
**Problem:** `*` might conflict with glob patterns or regex
**Solution:**
```typescript
// Escape wildcard in regex
const escaped = className.replace(/\*/g, "\\*");
```
### Pitfall 2: CSS Variable Parentheses vs Function Calls
**Problem:** `calc()`, `rgb()` might be mistaken for CSS variables
**Solution:**
```typescript
// Only match if preceded by utility prefix
/^(?:bg|text|border)-\(--[\w-]+\)$/; // Correct
```
### Pitfall 3: Variant Order Changes
**Problem:** v4 evaluates left-to-right, v3 was right-to-left
**Solution:**
- Don't reorder variants during transformation
- Preserve exact input order
- Add tests to verify order preservation
---
## Performance Considerations
### Pattern Matching
- New v4 patterns add complexity to regex matching
- Benchmark before/after: `pnpm benchmark`
- Expected impact: <5% slower (acceptable)
### Caching
- Wildcard selectors may reduce cache hit rate
- CSS variable parentheses are static (good for caching)
- Monitor cache performance in real projects
---
## Migration Guide for Users
When v4 support is complete, provide migration guide:
### For v3 Projects
```javascript
// tailwind.config.js
export default {
obfuscator: {
tailwindVersion: "3", // Explicit v3 mode
},
};
```
### For v4 Projects
```javascript
// tailwind.config.js
export default {
obfuscator: {
tailwindVersion: "4", // Explicit v4 mode
},
};
```
### Auto-Detection (Recommended)
```javascript
// tailwind.config.js
export default {
obfuscator: {
tailwindVersion: "auto", // Default - auto-detect
},
};
```
---
## Related Pages
- [v4 Features Analysis](./tailwind-v4-features-analysis) — full reference
- [v4 Quick Reference](./tailwind-v4-summary) — concise lookup
- [v4 Implementation Checklist](./v4-implementation-checklist) — action plan
---
## External Resources
### Official Tailwind CSS v4 Docs
- [v4.0 Release Blog Post](https://tailwindcss.com/blog/tailwindcss-v4)
- [Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide)
- [v4 Alpha Announcement](https://tailwindcss.com/blog/tailwindcss-v4-alpha)
### Community Resources
- [Moving from Tailwind 3 to 4 in Next.js 15](https://www.9thco.com/labs/moving-from-tailwind-3-to-tailwind-4)
- [Tailwind CSS v4 Breaking Changes](https://www.siaji.com/2025/02/03/Tailwind-CSS-v4-Breaking-Changes-and-Exciting-Features/)
- [shadcn/ui Tailwind v4 Guide](https://ui.shadcn.com/docs/tailwind-v4)
---
## Timeline & Milestones
### Milestone 1: Phase 1 Complete
- **Date:** [TBD]
- **Deliverables:** All critical breaking changes implemented
- **Verification:** All Phase 1 tests passing
### Milestone 2: Phase 2 Complete
- **Date:** [TBD]
- **Deliverables:** All high-value features implemented
- **Verification:** All Phase 2 tests passing
### Milestone 3: Release
- **Date:** [TBD]
- **Deliverables:**
- Full v4 support
- Documentation complete
- Migration guide published
- Blog post written
---
## Contributing
When adding new v4 features:
1. **Update this README** - Add to status section
2. **Update checklist** - Mark items as ✅
3. **Add tests** - Comprehensive test coverage
4. **Update docs** - User-facing documentation
5. **Update CHANGELOG** - Document changes
---
## Questions & Issues
### Common Questions
**Q: Do I need to migrate my v3 project to use this?**
A: No! The obfuscator supports both v3 and v4 simultaneously.
**Q: What happens if I use v4 syntax in a v3 project?**
A: The obfuscator will detect and handle it correctly (auto-detection mode).
**Q: Will this break my existing obfuscated CSS?**
A: No, the mapping is preserved. Existing obfuscated classes remain the same.
**Q: How do I know if I'm using v4 features?**
A: Check for `@import "tailwindcss"` in your CSS (v4) vs `@tailwind` directives (v3).
### Reporting Issues
If you find v4 patterns not being recognized:
1. Check the checklist to see if it's known
2. Create minimal reproduction case
3. Open issue with pattern example
4. Reference this research directory
---
## Acknowledgments
Research compiled from:
- Official Tailwind CSS v4 documentation
- Community blog posts and tutorials
- Analysis of `tailwindlabs/tailwindcss` source code
- Testing with real-world v4 projects
---
**Last Updated:** 2025-12-08
**Maintained By:** tailwindcss-obfuscator team
**Status:** Research complete, implementation in progress