Migrating from Django-Tailwind v1 to v2

Please note that the instructions below are for upgrading the Django package, not for the actual dependency on Tailwind CSS.

Django Tailwind2 v2 introduces many new features that aren’t available to projects generated with the previous version of the package. Thus if you want to get all the goodies v2 offers, you need to update your Django theme app.

Depending on how many customizations you have, the process can be smooth or bumpy.

Steps to upgrade

Let’s assume you’ve been using Django Tailwind for a while, and your TAILWIND_APP_NAME is theme.

  1. Edit INSTALLED_APPS in settings.py file and remove the 'theme' app.

  2. Rename the theme app directory to theme-legacy.

  3. Generate a new Tailwind theme app:

    python manage.py tailwind init
    

    Name it the same as your previous app: theme.

  4. Add the 'theme' back to INSTALLED_APPS;

  5. Make sure that INTERNAL_IPS list is present in the settings.py file and contains the 127.0.0.1 ip address:

     ```python
     INTERNAL_IPS = [
         "127.0.0.1",
     ]
     ```
    
  6. Copy theme-legacy/static_src/src to theme/static_src/src;

  7. If you have a file named theme/static_src/src/styles.scss, rename it to theme/static_src/src/styles.css. In v2 we dropped support for SASS, but POSTCSS should work just fine. Unless you’ve used advanced SASS features, which is unlikely;

  8. Open theme-legacy/static_src/tailwind.config.js and compare it with theme/static_src/tailwind.config.js, if you have customizations there, like custom colors, variables, etc., copy them to theme/static_src/tailwind.config.js;

  9. Notice the plugins listed in theme/static_src/tailwind.config.js. We’ve now included the four official Tailwind CSS plugins there. If you see that your forms look weird after the update, you probably don’t need the official @tailwindcss/forms package, so disable it by removing the following line:

    require('@tailwindcss/forms'),
    

    from the theme/static_src/tailwind.config.js.

  10. Copy theme-legacy/templates to theme/templates;

  11. Open theme/templates/base.html and add {% load tailwind_tags %} to the beginning of the file. Then, replace:

    <link
      rel="stylesheet"
      href="{% static 'css/styles.css' %}"
      type="text/css"
    />
    

    with

    {% tailwind_css %}
    
  12. To install dependencies, run the following command:

    python manage.py tailwind install
    
  13. Now start the development server:

    python manage.py tailwind start
    
  14. If all went well, you should now be on the latest version of Django Tailwind with your previous styles intact.