Skip to content

Commit 4dbceda

Browse files
michael-yinmichael-yin
committed
update doc
1 parent d7b4acf commit 4dbceda

File tree

4 files changed

+287
-169
lines changed

4 files changed

+287
-169
lines changed

‎docs/setup_with_django.md‎

Lines changed: 66 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Setup With Django
22

3+
We will show you how to integrate `python-webpack-boilerplate` with Django and use Tailwind v4 as the style solution.
4+
35
## Install Package
46

57
```bash
@@ -43,14 +45,20 @@ INSTALLED_APPS = [
4345

4446
Let's run Django command to create frontend project from the templates
4547

46-
```bash hl_lines="3 4"
48+
```bash
4749
$ python manage.py webpack_init
48-
49-
project_slug [frontend]:
50-
run_npm_command_at_root [y]:
51-
[SUCCESS]: Frontend app 'frontend' has been created.
50+
[1/3] project_slug (frontend):
51+
[2/3] run_npm_command_at_root (y):
52+
[3/3] Select style_solution
53+
1 - tailwind
54+
2 - bootstrap
55+
3 - scss
56+
Choose from [1/2/3] (1): 1
57+
[SUCCESS]: Frontend app 'frontend' has been created. To know more, check https://python-webpack-boilerplate.rtfd.io/en/latest/frontend/
5258
```
5359

60+
Here we use the default `Tailwind CSS` as our style solution.
61+
5462
Now a new `frontend` directory is created which contains pre-defined files for our frontend project.
5563

5664
```bash
@@ -75,9 +83,9 @@ Now a new `frontend` directory is created which contains pre-defined files for o
7583

7684
```bash
7785
$ node -v
78-
v20.10.0
86+
v22.13.1
7987
$ npm -v
80-
10.2.3
88+
10.9.2
8189
```
8290

8391
Now go to directory which contains `package.json`, by default, it is root directory.
@@ -178,39 +186,42 @@ TEMPLATES = [
178186

179187
Add `index.html` to the above `example/templates`
180188

181-
```html hl_lines="1 9 10 20"
189+
```html
182190
{% load webpack_loader static %}
183191

184192
<!DOCTYPE html>
185193
<html>
186194
<head>
187-
<meta charset="utf-8" />
188195
<title>Index</title>
189-
<script src="https://cdn.tailwindcss.com"></script>
196+
<meta charset="utf-8" />
197+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
190198
{% stylesheet_pack 'app' %}
191-
{% javascript_pack 'app' attrs='defer' %}
192199
</head>
193200
<body>
194201

195-
<div class="bg-gray-50 py-5" data-jumbotron>
196-
<div class="container mx-auto px-4 py-10">
197-
<h1 class="text-4xl font-bold leading-tight">Welcome to Our Website</h1>
198-
<p class="mt-4 text-lg">This is a hero section built using Tailwind CSS.</p>
199-
<button class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 mt-6 rounded-lg">Get Started</button>
202+
<div class="jumbotron py-5">
203+
<div class="w-full max-w-7xl mx-auto px-4">
204+
<h1 class="text-4xl mb-4">Hello, world!</h1>
205+
<p class="mb-4">This is a template for a simple marketing or informational website. It includes a large callout called a
206+
jumbotron and three supporting pieces of content. Use it as a starting point to create something more unique.</p>
207+
208+
<p><a class="btn-blue mb-4" href="#" role="button">Learn more »</a></p>
209+
200210
<div class="flex justify-center">
201211
<img src="{% static 'vendors/images/webpack.png' %}"/>
202212
</div>
203213
</div>
204214
</div>
205215

216+
{% javascript_pack 'app' %}
217+
206218
</body>
207219
</html>
208220
```
209221

210-
1. Here we use `Tailwind CDN` to help user to do quick test, please remove it later.
211-
2. We `load webpack_loader` at the top of the template
212-
3. We can still use `static` tag to import image from the frontend project.
213-
4. We use `stylesheet_pack` and `javascript_pack` to load CSS and JS bundle files to Django
222+
1. We `load webpack_loader` at the top of the template
223+
2. We can still use `static` tag to import image from the frontend project.
224+
3. We use `stylesheet_pack` and `javascript_pack` to load CSS and JS bundle files to Django
214225

215226
!!! note
216227
1. When your javascript and css files grow bigger and bigger, code splitting would be done automatically by Webpack.
@@ -220,6 +231,9 @@ Add `index.html` to the above `example/templates`
220231
## Manual Test
221232

222233
```bash
234+
# restart webpack to let Tailwind auto scan
235+
$ npm run watch
236+
223237
$ python manage.py migrate
224238
$ python manage.py runserver
225239
```
@@ -233,7 +247,38 @@ dom ready
233247
jumbotron.js:8 Jumbotron initialized for node: [object HTMLDivElement]
234248
```
235249

236-
The source code can also be found in the [Examples](https://github.com/AccordBox/python-webpack-boilerplate/tree/master/examples/)
250+
## Explicitly Specify Source Files
251+
252+
Even Tailwind 4 can AUTO scan all project files in the project directory, we still recommend to explicitly specify the source files to improve performance.
253+
254+
Below is an example of `frontend/src/styles/index.css`
255+
256+
```css
257+
/*import tailwindcss and disable automatic source detection*/
258+
@import "tailwindcss" source(none);
259+
260+
/*register frontend directory*/
261+
@source "../";
262+
263+
/*register django templates*/
264+
@source "../../../django_tailwind_app/**/*.html";
265+
266+
.jumbotron {
267+
/*should be relative path of the entry css file*/
268+
background-image: url("../../vendors/images/sample.jpg");
269+
background-size: cover;
270+
}
271+
272+
@layer components{
273+
.btn-blue {
274+
@apply inline-flex items-center;
275+
@apply px-4 py-2;
276+
@apply font-semibold rounded-lg shadow-md;
277+
@apply text-white bg-blue-500;
278+
@apply hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-400/50;
279+
}
280+
}
281+
```
237282

238283
## Live Reload
239284

‎docs/setup_with_tailwind.md‎

Lines changed: 41 additions & 147 deletions
Original file line numberDiff line numberDiff line change
@@ -1,175 +1,69 @@
1-
# Tailwind CSS
1+
# Tailwind CSS V4
22

3-
This guide will help you install and config `Tailwind v3`
4-
5-
## Install Dependency
6-
7-
In directory which contains the `package.json`, install `tailwindcss` and `postcss-import`
3+
From `python-webpack-boilerplate>=1.0.4`, we can choose `tailwind` as the style solution when creating the frontend project.
84

95
```bash
10-
$ npm install -D tailwindcss@latest postcss-import
6+
(venv) python manage.py webpack_init
7+
[1/3] project_slug (frontend):
8+
[2/3] run_npm_command_at_root (y):
9+
[3/3] Select style_solution
10+
1 - tailwind
11+
2 - bootstrap
12+
3 - scss
13+
Choose from [1/2/3] (1): 1
14+
[SUCCESS]: Frontend app 'frontend' has been created. To know more, check https://python-webpack-boilerplate.rtfd.io/en/latest/frontend/
1115
```
1216

13-
Once done, update `postcss.config.js`
17+
Just choose `tailwind` as the style_solution, the Tailwind V4 will be ready for you.
1418

15-
```
16-
// https://tailwindcss.com/docs/using-with-preprocessors
17-
18-
module.exports = {
19-
plugins: [
20-
require('postcss-import'),
21-
require('tailwindcss/nesting')(require('postcss-nesting')),
22-
require('tailwindcss'),
23-
require('postcss-preset-env')({
24-
features: { 'nesting-rules': false }
25-
}),
26-
]
27-
};
28-
```
19+
## Install Dependency
2920

30-
Next, generate a config file for your project using the Tailwind CLI utility included when you install the `tailwindcss` npm package
21+
In directory which contains the `package.json`
3122

3223
```bash
33-
$ npx tailwindcss init
24+
# install dependency packages
25+
$ npm install
26+
# run webpack in watch mode
27+
$ npm run watch
3428
```
3529

36-
Now `tailwind.config.js` is generated
37-
38-
```js
39-
module.exports = {
40-
content: [],
41-
theme: {
42-
extend: {},
43-
},
44-
plugins: [],
45-
}
46-
```
47-
48-
!!! note
49-
50-
Please make sure `tailwind.config.js` exists in the same directory as `postcss.config.js`
51-
52-
## JIT
53-
54-
From Tailwind V3, it enabled `JIT` (Just-in-Time) all the time.
55-
56-
> Tailwind CSS works by scanning all of your HTML, JavaScript components, and any other template files for class names, then generating all of the corresponding CSS for those styles.
57-
58-
> In order for Tailwind to generate all of the CSS you need, it needs to know about every single file in your project that contains any Tailwind class names.
59-
60-
So we should config `content` section of the `tailwind.config.js`, then Tailwind will know which css classes are used.
61-
62-
Let's update *frontend/tailwind.config.js*
63-
64-
```js
65-
const Path = require("path");
66-
const pwd = process.env.PWD;
67-
68-
// We can add current project paths here
69-
const projectPaths = [
70-
Path.join(pwd, "../example/templates/**/*.html"),
71-
// add js file paths if you need
72-
];
73-
74-
const contentPaths = [...projectPaths];
75-
console.log(`tailwindcss will scan ${contentPaths}`);
76-
77-
module.exports = {
78-
content: contentPaths,
79-
theme: {
80-
extend: {},
81-
},
82-
plugins: [],
83-
}
84-
```
30+
## Explicitly Specify Source Files
8531

86-
Notes:
32+
Even Tailwind 4 can AUTO scan all project files in the project directory, we still recommend to explicitly specify the source files to improve performance.
8733

88-
1. Here we add Django templates path to the `projectPaths`
89-
1. And then we pass the `contentPaths` to the `content`
90-
1. The final built css file will contain css classes used in the Django templates
34+
Below is an example
9135

92-
## Import Tailwind CSS
36+
```css
37+
/*import tailwindcss and disable automatic source detection*/
38+
@import "tailwindcss" source(none);
9339

94-
Update *src/styles/index.scss*
40+
/*register frontend directory*/
41+
@source "../";
9542

96-
```scss
97-
@import "tailwindcss/base";
98-
@import "tailwindcss/components";
99-
@import "tailwindcss/utilities";
43+
/*register django templates*/
44+
@source "../../../django_tailwind_app/**/*.html";
10045

10146
.jumbotron {
102-
// should be relative path of the entry scss file
103-
background-image: url("../../vendors/images/sample.jpg");
104-
background-size: cover;
47+
/*should be relative path of the entry css file*/
48+
background-image: url("../../vendors/images/sample.jpg");
49+
background-size: cover;
10550
}
10651

107-
.btn-blue {
108-
@apply inline-block px-4 py-2;
109-
@apply font-semibold rounded-lg shadow-md;
110-
@apply bg-blue-500 text-white;
111-
@apply hover:bg-blue-700 focus:outline-none;
112-
@apply focus:ring-2 focus:ring-blue-400 focus:ring-opacity-75;
52+
@layer components{
53+
.btn-blue {
54+
@apply inline-flex items-center;
55+
@apply px-4 py-2;
56+
@apply font-semibold rounded-lg shadow-md;
57+
@apply text-white bg-blue-500;
58+
@apply hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-400/50;
59+
}
11360
}
11461
```
11562

116-
```
117-
$ npm run start
118-
119-
tailwindcss will scan django_basic/example/templates/**/*.html
120-
```
121-
122-
Edit Django template `templates/index.html`
123-
124-
```html hl_lines="8 28"
125-
{% load webpack_loader static %}
126-
127-
<!DOCTYPE html>
128-
<html>
129-
<head>
130-
<meta charset="utf-8" />
131-
<title>Index</title>
132-
{% stylesheet_pack 'app' %}
133-
</head>
134-
<body>
135-
136-
<div class="jumbotron">
137-
<div class="w-full max-w-7xl p-4 mx-auto">
138-
<h1 class="text-4xl mb-4">Hello, world!</h1>
139-
140-
<p class="mb-2">This is a template for a simple marketing or informational website. It includes a large callout called a
141-
jumbotron and three supporting pieces of content. Use it as a starting point to create something more unique.</p>
142-
143-
<p class="mb-2"><a class="btn-blue" href="#" role="button">Learn more »</a></p>
144-
145-
<div class="flex justify-center">
146-
<img src="{% static 'vendors/images/webpack.png' %}"/>
147-
</div>
148-
149-
</div>
150-
</div>
151-
152-
{% javascript_pack 'app' %}
153-
154-
</body>
155-
</html>
156-
```
157-
158-
```bash
159-
$ python manage.py runserver
160-
```
161-
162-
![TailwindCSS example](images/tailwind-example.png)
163-
16463
## Live Reload
16564

166-
When you add Tailwind css class in Django template, it would be cool if the page can `auto live realod`, please check link below
167-
16865
[Live Reload Support](live_reload.md)
16966

170-
## Tutorials
171-
172-
To learn more about Tailwind and Django, you can check
67+
## Tailwind V3
17368

174-
1. [Django Tailwind CSS Alpine.js Tutorial](https://www.accordbox.com/blog/django-tailwind-css-alpinejs-tutorial/)
175-
2. [wagtail-tailwind-blog](https://github.com/AccordBox/wagtail-tailwind-blog)
69+
If you still want to install Tailwind V3, please check [Tailwind CSS V3](setup_with_tailwind3.md)

0 commit comments

Comments
 (0)