Troubleshooting

FAQ & Common Issues

Solutions to the most common problems, performance optimization tips, and migration guides.

🔧 Common Issues

Problem: CSS Not Updating After Changes

Symptoms: You add a new class like bg-red-500 to your HTML, but it doesn't show up in the browser.

Solution:

  1. Make sure tailpyscss watch is running.
  2. Check the terminal for build errors.
  3. Hard refresh your browser (Ctrl+Shift+R on Windows/Linux, Cmd+Shift+R on Mac).
  4. Clear browser cache if the issue persists.

Problem: Utility Classes Not Generating

Symptoms: You use text-primary but it doesn't exist in the CSS.

Solution:

  1. Check tailpy_config.py - does primary exist in the colors dict?
  2. Ensure the file containing the class is being scanned (.py, .html, .js).
  3. Run tailpyscss build manually to see debug output.
# tailpy_config.py
config = {
    "colors": {
        "primary": "#4f46e5",  # Now .text-primary will work
    }
}

Problem: ModuleNotFoundError: No module named 'tailpyscss'

Solution:

  1. Ensure you're in the correct virtual environment.
  2. Run pip install tailpyscss again.
  3. Check pip list to verify installation.

⚡ Performance Optimization

Problem: Slow Build Times

Symptoms: tailpyscss build takes more than 5 seconds.

Solutions:

  1. Reduce Scan Scope: Add .tailpyignore to exclude large directories: 
    # .tailpyignore
__pycache__/
*.pyc
venv/
env/
.git/
tests/
migrations/
  2. Use Fewer Dynamic Classes: Avoid generating thousands of unused color variants.
  3. Tree Shaking: Ensure you're using the ui="..." attribute for components to enable tree shaking.

Problem: Large CSS File Size

Symptoms: styles.css is over 500KB.

Solutions:

  1. Purge Unused Classes: Make sure only used classes are being scanned.
  2. Built-in Minification: TailPySCSS automatically minifies CSS when you run tailpyscss build using LibSass's compressed output style. No external tools needed!
  3. Use CDN: Serve CSS from a CDN with gzip/brotli compression for even smaller file sizes.

🚀 Migration Guides

Migrating from Tailwind CSS

TailPySCSS utility classes are 95% compatible with Tailwind. Here are the key differences:

✅ What's the Same

  • Utility classes: p-4, text-center, bg-white
  • Responsive prefixes: md:flex, lg:grid-cols-3
  • Hover states: hover:bg-blue-500

❌ What's Different

  • No JIT Compiler: TailPySCSS uses static generation. Add colors to tailpy_config.py instead of arbitrary values like bg-[#1da1f2].
  • No @apply in HTML: Use SCSS files for @apply, not inline.
  • Different Config: Use tailpy_config.py (Python) instead of tailwind.config.js.

Migration Checklist

  1. Install TailPySCSS: pip install tailpyscss
  2. Run tailpyscss init
  3. Port your tailwind.config.js colors/spacing to tailpy_config.py
  4. Replace <link> to Tailwind CDN with static/css/styles.css
  5. Run tailpyscss build

Migrating from Bootstrap

Bootstrap uses semantic classes. TailPySCSS uses utility classes. You'll need to refactor your HTML.

Bootstrap → TailPySCSS Equivalents

<!-- BEFORE (Bootstrap) -->
<button class="btn btn-primary">Click Me</button>

<!-- AFTER (TailPySCSS) -->
<button class="bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600">Click Me</button>

<!-- BEFORE (Bootstrap) -->
<div class="container">
    <div class="row">
        <div class="col-md-6">...</div>
    </div>
</div>

<!-- AFTER (TailPySCSS) -->
<div class="max-w-7xl mx-auto px-4">
    <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
        <div>...</div>
    </div>
</div>

❓ Frequently Asked Questions

Can I use TailPySCSS with React/Vue?

Technically yes, but it's designed for Python backends (Flask, Django). For React/Vue, stick with Tailwind CSS as it integrates better with Vite/Webpack.

Does it work with Jinja2/Django templates?

Yes! It scans .html files, so Jinja2 and Django templates work perfectly.

Can I use custom fonts?

Yes. Import them in your styles/main.scss: 

@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap');

body {
    font-family: 'Inter', sans-serif;
}

Is it production-ready?

Yes. It's been used in production by multiple companies. Just make sure to run tailpyscss build in your deployment pipeline.