To convert a Laravel project from Tailwind to Bootstrap, you must remove the existing CSS dependencies, install the Bootstrap library via npm or Composer, and replace all utility classes in your Blade templates with standard Bootstrap components. This process ensures your application maintains its structure while adopting a new design system without breaking existing functionality or routing logic.
Removing Existing Dependencies
The first step involves cleaning up the current styling infrastructure. Since Laravel projects typically use Vite for asset management, you need to adjust both your package manager requirements and your configuration files. Begin by uninstalling the Tailwind CSS packages from your
package.json. Run the following command in your terminal to remove these dependencies:
npm uninstall tailwindcss postcss autoprefixer
Next, you should delete the configuration files associated with Tailwind. Remove the
tailwind.config.js file from your root directory. If you are using PostCSS, you may also need to update or remove the
postcss.config.js file depending on whether other plugins rely on it. Clearing these files prevents conflicts during the installation of the new framework.
Installing Bootstrap Framework
With the old styles removed, you can now introduce Bootstrap. The most straightforward method is using npm to install the latest version of Bootstrap and its dependencies. Execute the following command in your project root:
npm install bootstrap @popperjs/core
This installs the core Bootstrap CSS and JavaScript libraries along with Popper.js, which is required for interactive components like dropdowns and tooltips. After installation, verify that the
node_modules directory contains the
bootstrap folder. You do not need to configure Webpack or Vite manually for basic usage, but you must ensure your entry point imports these assets correctly.
Updating Asset Entry Points
Laravel uses Vite to compile assets defined in
resources/js/app.js (or
app.ts). You need to modify this file to import Bootstrap instead of Tailwind directives. Open
resources/js/app.js and remove any lines referencing
tailwindcss or
@tailwind. Add the following import statements to load Bootstrap's CSS and JavaScript:
import 'bootstrap/dist/css/bootstrap.min.css';
import * as bootstrap from 'bootstrap';
If your project relies on specific Sass variables or custom overrides, you might prefer importing the SCSS source files instead. In that case, install the Sass loader if not already present and import the main Bootstrap SCSS file. However, for most conversions, the compiled CSS is sufficient and easier to manage. Save the file and run
npm run dev to compile the assets. This generates the updated CSS and JS bundles in the
public/build directory.
Refactoring Blade Templates
The most labor-intensive part of this migration is updating your Blade views. Tailwind uses utility-first classes (e.g.,
p-4 bg-white rounded), while Bootstrap uses semantic component classes (e.g.,
card p-4 bg-white). You will need to scan your
resources/views directory and replace class attributes.
For example, replace Tailwind grid systems with Bootstrap's row and column classes. A Tailwind layout using
grid grid-cols-3 gap-4 becomes
row g-4 with child elements having
col-md-4. Buttons require changing from
bg-blue-500 text-white px-4 py-2 to
btn btn-primary. Forms also need adjustment; input groups and validation error displays should follow Bootstrap's form-control patterns.
It is advisable to work section by section rather than attempting a global find-and-replace. Start with navigation bars and footers, then move to content cards and forms. Ensure that responsive behavior is maintained by testing different screen sizes after each refactor. Bootstrap’s responsive breakpoints differ slightly from Tailwind’s, so you may need to adjust breakpoint-specific classes like
md: to
md- prefixes.
Verifying Functionality and Assets
After refactoring the templates, clear your browser cache and reload the application. Check for broken styles, missing icons, or non-functional interactive elements. If dropdowns or modals do not open, ensure that the Bootstrap JavaScript bundle is loaded correctly in your layout file. The script tag should reference the compiled JS file from Vite:
@vite(['resources/js/app.js'])
If you encounter issues with specific components, check the browser console for errors related to jQuery or Popper. Modern Bootstrap versions do not depend on jQuery, so avoid including legacy scripts unless necessary. Additionally, verify that any custom CSS overrides placed in separate stylesheet files are compatible with the new class names.
For more information on managing resources in Laravel, see
Displaying Courses and Categories in Laravel: A Guide.
Frequently Asked Questions
Will converting to Bootstrap break my existing JavaScript logic?
No, the conversion primarily affects CSS classes and HTML structure, leaving your backend logic and Vue/Livewire components intact. However, you must ensure that any JavaScript interacting with DOM elements uses selectors compatible with the new Bootstrap class names.
How do I handle custom Tailwind utilities that have no Bootstrap equivalent?
You can extend Bootstrap by adding custom CSS rules in a separate stylesheet imported after the main Bootstrap CSS. Alternatively, use inline styles or create small utility classes in your own SCSS file to mimic the specific spacing or color properties you need.
Can I keep Tailwind for some parts and use Bootstrap for others?
While technically possible, mixing two CSS frameworks often leads to specificity conflicts and increased file sizes. It is highly recommended to choose one framework per project to maintain consistency and simplify maintenance.
What should I do if my responsive layout looks broken after migration?
Check the breakpoint prefixes; Tailwind uses
sm:,
md:, etc., while Bootstrap uses
-sm,
-md. Also, ensure that container widths and padding margins match Bootstrap’s default settings, which may differ from Tailwind’s reset values.
Do I need to reinstall npm packages if I switch back to Tailwind later?
Yes, you would need to reinstall the Tailwind packages and remove Bootstrap dependencies. It is good practice to commit your
package.json changes at each major step so you can revert if needed.