You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+54-48Lines changed: 54 additions & 48 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@ development server instead of the Webpack Dev Server.**
10
10
11
11
## Getting Started <!-- omit in toc -->
12
12
13
-
[Michael Soriano](https://github.com/michaelsoriano)wrote a great tutorial for using `create-react-wptheme`. It provides a lot more detail than this `readme` and the screen shots are really helpful.
13
+
[Michael Soriano](https://github.com/michaelsoriano)is writing a tutorial for creating a theme using React. He uses `create-react-wptheme` for the initial setup. He provides a lot more detail than this `readme` and the screen shots are really helpful.
14
14
15
15
Check it out:
16
16
<br>
@@ -21,12 +21,13 @@ For more details check out the rest of this document.
- When it finishes it'll tell you to change into your new theme's folder and run the Nodejs watcher (replace "my_react_theme" with the same name you used in the previous step):
48
49
-`cd my_react_theme/react-src`
49
-
-`npm run wpstart`
50
+
-`npm run start`
50
51
- That sets up the theme so that it can be seen in the WordPress admin area.
51
52
-**Go there now and set your WordPress site to use this theme.**
52
53
- View the site in your browser with the new theme.
@@ -56,7 +57,7 @@ To create a WordPress theme using the `create-react-wptheme`, follow these steps
56
57
-**You can revoke write access after the setup has completed.**
57
58
- Interested (paranoid?) about what it's doing? Check out the file: `<your theme folder name>/index.php`
58
59
- When that's done the theme tells you to `Please restart the Nodejs watcher now...`
59
-
- To do that, go back to your command prompt where you first ran `npm run wpstart` and rerun that same command again.
60
+
- To do that, go back to your command prompt where you first ran `npm run start` and rerun that same command again.
60
61
- In a few seconds you should see your browser load with the standard create-react-app page, but it's running as a WordPress theme!
61
62
62
63
## Updating Existing Themes
@@ -73,7 +74,7 @@ If your theme uses TypeScript, you'll need to run a second command (`create-reac
73
74
74
75
**Important note for Yarn users: be sure to use `yarn add` instead of `npm install` in the above commands.**
75
76
76
-
## Coding with React
77
+
## Developing Your Theme
77
78
78
79
### React Tutorials
79
80
@@ -83,59 +84,31 @@ If you're looking at a React tutorial on the web, you can use `create-react-wpth
So for example, if the tutorial instructs you to edit the `src/App.js` file, then for you, that file would actually be located at (assuming you're already in your new theme's root folder):
87
+
So for example, if the tutorial instructs you to edit the `src/App.js` file, then for you, that file would actually be located at:
The authors of the original `create-react-app` say that using the "Public" folder (found at `react-src/public` in your new theme's folder)
93
-
is a last ditch "escape hatch" for adding otherwise-hard-to-deal-with files.
93
+
The authors of the original `create-react-app` say that using the "Public" folder (found at `react-src/public` in your new theme's folder) is a last ditch "escape hatch" for adding otherwise-hard-to-deal-with files.
94
94
95
-
But for this project, I've decided to use it for all things that you'd put into a normal WordPress theme (e.g. functions.php, etc.).
96
-
So any PHP, hard-coded CSS, and/or hard-coded JS (like other JS libraries that you'd like to reference globally (I don't judge)), can go into
97
-
the public folder.
95
+
But for this project, I've decided to use it for all things that you'd put into a normal WordPress theme (e.g. functions.php, etc.). So any PHP, hard-coded CSS, and/or hard-coded JS (like other JS libraries that you'd like to reference globally (I don't judge)), can go into the public folder.
98
96
99
-
**In addition, any changes made to CSS, JS, and PHP files in the Public folder will cause a rebuild to happen.**
100
-
Which is unlike `create-react-app` which ignores most of the files in the Public folder.
101
-
102
-
I'm not sure if making the Public folder more important is the right decision yet. Maybe I should have created a separate folder for this.
103
-
I guess time will tell.
97
+
**In addition, any changes made to CSS, JS, and PHP files in the Public folder will cause a rebuild to happen.** Which is unlike `create-react-app` which ignores most of the files in the Public folder.
104
98
105
99
### Dev Configuration
106
100
107
-
After you've created a new theme, and all the setup is done, you'll find a file named `react-src/user.dev.json` that has some configuration options
108
-
that you can mess with if you need to.
109
-
110
-
### Build Configuration
111
-
112
-
The `react-src/user.prod.json` configuration file is read when you run `npm run wpbuild`. The only option in there is setting the "homepage"
113
-
which controls the relative linking to files in your theme. The "homepage" setting in your main `package.json` file is used during development (and build by default).
114
-
During development, this is probably what you want. But if you know your production server will have a different root, then you can set the homepage to be different during
115
-
a production build.
116
-
117
-
For example:
118
-
119
-
- Your WordPress dev server is running at http<nolink>://localhost/wordpress
120
-
- the homepage setting in your main package.json file will probably work just fine.
121
-
- The homepage line in your main package.json be something like: `"homepage": "/wordpress/wp-content/themes/<your theme's folder name>"`
122
-
- But you know that your production server runs WordPress from the root: http<nolink>://mycoolblog.com/
123
-
- In this case you want to remove the `/wordpress` part, so set the "homepage" line in your `user.prod.json` file to:
- Note that if you then view your theme on your dev server, it will most likely be broken. But will hopefully look
127
-
correct on your production server.
101
+
After you've created a new theme, and all the setup is done, you'll find a file named `react-src/user.dev.json` that has some configuration options that you can mess with if you need to.
128
102
129
103
### HTTPS/SSL Support
130
104
131
-
If you develop using SSL (i.e. HTTPS), then you might want to run the "Browser Refresh Server" under SSL as well. Especially if you use Firefox, see here:
If you develop using SSL (i.e. HTTPS), then you might want to run the `Browser Refresh Server` under SSL as well. Especially if you use Firefox, see here: [Firefox Websocket security issue](https://stackoverflow.com/questions/11768221/firefox-websocket-security-issue).
133
106
134
-
To configure the Browser Refresh Server to use SSL, follow these steps:
107
+
To configure the `Browser Refresh Server` to use SSL, follow these steps:
135
108
136
109
- These instructions use the command prompt.
137
110
- Assuming you've already created a theme using `create-react-wptheme`, change directory into the `react-src` folder in your theme's folder
138
-
- Be sure to follow **all the instructions** under the **Usage** section at the top of this document.
111
+
- Be sure to follow **all the instructions** under the **Usage** section at the top of this document. You need to complete the PHP portion of the setup before you can configure SSL.
139
112
- Windows example: `cd C:\xampp\htdocs\wordpress\wp-content\themes\<your theme's folder name>\react-src`
140
113
- Mac or \*nix example: `cd /xampp/htdocs/wordpress/wp-content/themes/<your theme's folder name>/react-src`
141
114
- Create a new folder to hold you're development SSL certificate and key.
@@ -166,7 +139,44 @@ To configure the Browser Refresh Server to use SSL, follow these steps:
166
139
- For example, if you're using host `127.0.0.1` and port `8090` as shown above, then open your browser to:
167
140
- https<nolink>://127.0.0.1:8090/
168
141
- From there you'll get the standard browser warning about self-signed certificates and get the option to add an exception.
169
-
- Once you've finished adding an exception to your browser, you'll need to refresh the tab with your development theme to force a reconnect to the Browser Refresh Server.
142
+
- Once you've finished adding an exception to your browser, you'll need to refresh the tab with your development theme to force a reconnect to the `Browser Refresh Server`.
143
+
144
+
## Deploying Your Theme
145
+
146
+
While you're actively developing your theme, the files are not optimized for production. Before you put your theme into production, you need to run the `build` command.
147
+
148
+
In a command prompt, change into the `react-src` folder of you theme and run this command:
149
+
`npm run build`
150
+
151
+
When that command finishes, your optimized files are located in a folder that can be deployed to your production server.
152
+
153
+
Here's an example showing which folder to deploy to your server:
154
+
155
+
- ...wp-content
156
+
- themes
157
+
- my-theme
158
+
- my-theme `<- deploy this folder to your production server's themes folder`
159
+
- react-src
160
+
- !READY_TO_DEPLOY!.txt
161
+
162
+
163
+
### Dealing With Differing Paths Between DEV and PROD
164
+
165
+
The `react-src/user.prod.json` configuration file is read when you run `npm run build`. The only option in there is setting the "homepage"
166
+
which controls the relative linking to files in your theme. The "homepage" setting in your main `package.json` file is used during development (and build by default).
167
+
168
+
During development, this is probably what you want. But **if you know your production server has a different root**, then you can set the homepage to be different during a production build.
169
+
170
+
For example:
171
+
172
+
- Your WordPress dev server is running at http<nolink>://localhost/wordpress
173
+
- the homepage setting in your main package.json file will probably work just fine.
174
+
- The homepage line in your main package.json be something like: `"homepage": "/wordpress/wp-content/themes/<your theme's folder name>"`
175
+
- But you know that your production server runs WordPress from the root: http<nolink>://mycoolblog.com/
176
+
- In this case you want to remove the `/wordpress` part, so set the "homepage" line in your `user.prod.json` file to:
0 commit comments