{"id":14954971,"url":"https://github.com/devloco/create-react-wptheme","last_synced_at":"2025-04-14T11:28:13.403Z","repository":{"id":41300869,"uuid":"137653674","full_name":"devloco/create-react-wptheme","owner":"devloco","description":"Create modern, React-enabled WordPress themes with a single command.","archived":false,"fork":false,"pushed_at":"2024-11-20T13:13:30.000Z","size":626,"stargazers_count":362,"open_issues_count":25,"forks_count":61,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-03-31T07:04:05.166Z","etag":null,"topics":["create-react-app","php","react","react-theme","react-tutorial","react-wordpress-themes","reactjs","wordpress","wordpress-api","wordpress-development","wordpress-server","wordpress-starter-theme","wordpress-theme"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devloco.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-17T12:33:19.000Z","updated_at":"2025-01-25T14:39:51.000Z","dependencies_parsed_at":"2024-09-21T22:00:42.348Z","dependency_job_id":"c93ff7a5-a707-4a24-9427-712fd59a63fd","html_url":"https://github.com/devloco/create-react-wptheme","commit_stats":{"total_commits":144,"total_committers":2,"mean_commits":72.0,"dds":0.4375,"last_synced_commit":"0999330254cc5970901198a925d94a542e365310"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devloco%2Fcreate-react-wptheme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devloco%2Fcreate-react-wptheme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devloco%2Fcreate-react-wptheme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devloco%2Fcreate-react-wptheme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devloco","download_url":"https://codeload.github.com/devloco/create-react-wptheme/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247615375,"owners_count":20967184,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["create-react-app","php","react","react-theme","react-tutorial","react-wordpress-themes","reactjs","wordpress","wordpress-api","wordpress-development","wordpress-server","wordpress-starter-theme","wordpress-theme"],"created_at":"2024-09-24T13:10:19.194Z","updated_at":"2025-04-07T08:08:31.319Z","avatar_url":"https://github.com/devloco.png","language":"JavaScript","readme":"# Create React WP Theme \u003c!-- omit in toc --\u003e\n\n## Still Up To Date!\n\nMay 6, 2020\n\u003cbr /\u003e\nJust wanted to note that version [v3.4.1](https://github.com/facebook/create-react-app/releases/tag/v3.4.1) of [Create-React-App](https://create-react-app.dev/) is still the latest.\n\nIf you have a theme made with an earlier version of `create-react-wptheme` and want to update it to the latest code, [just follow these instructions](#updating-existing-themes).\n\n---\n\n## Getting Started \u003c!-- omit in toc --\u003e\n\n[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.\n\nCheck it out:\n\u003cbr\u003e\n[Let's build a WordPress theme with React: Part 1 (Setup)](http://michaelsoriano.com/wordpress-theme-react-part-1-setup/)\n\n## Readme Contents \u003c!-- omit in toc --\u003e\n\nFor more details check out the rest of this document.\n\n-   [Creating a New Theme](#creating-a-new-theme)\n-   [Updating Existing Themes](#updating-existing-themes)\n    -   [Updating TypeScript Types](#updating-typescript-types)\n-   [Developing Your Theme](#developing-your-theme)\n    -   [React Tutorials](#react-tutorials)\n    -   [The Public Folder](#the-public-folder)\n    -   [Dev Configuration](#dev-configuration)\n    -   [HTTPS/SSL Support](#httpsssl-support)\n-   [Deploying Your Theme](#deploying-your-theme)\n    -   [Dealing With Differing Paths Between DEV and PROD](#dealing-with-differing-paths-between-dev-and-prod)\n-   [Goals](#goals)\n-   [Acknowledgements](#acknowledgements)\n-   [License](#license)\n\n## Creating a New Theme\n\nTo create a WordPress theme using `create-react-wptheme`, follow these steps.\n\n-   Make sure your WordPress server is up and running.\n-   Change dir into your WordPress themes folder (**this is just an example, use your real themes folder**).\n    -   Windows: `cd C:\\xampp\\htdocs\\wordpress\\wp-content\\themes`\n    -   Mac or \\*nix: `cd /xampp/htdocs/wordpress/wp-content/themes`\n-   Use `npx create-react-wptheme` to make a new theme\n    -   For example: (**replace \"my_react_theme\" with whatever you want your theme to be named**):\n    -   `npx create-react-wptheme my_react_theme`\n        -   If you want to use TypeScript, then the command would be:\n        -   `npx create-react-wptheme my_react_theme --typescript`\n-   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):\n    -   `cd my_react_theme/react-src`\n    -   `npm run start`\n-   That sets up the theme so that it can be seen in the WordPress admin area.\n    -   **Go there now and set your WordPress site to use this theme.**\n-   View the site in your browser with the new theme.\n    -   **You must do this as it does some extra setup via PHP.**\n    -   **If you get PHP errors, most likely your web server doesn't have write access to your theme.**\n        -   Write access for your web server is only needed during this setup step.\n        -   **You can revoke write access after the setup has completed.**\n        -   Interested (paranoid?) about what it's doing? Check out the file: `\u003cYour Theme's Root Folder\u003e/index.php`\n    -   When that's done you'll see: `Now, back in your command prompt, rerun the \"start\" script again...`\n    -   To do that, go back to your command prompt where you first ran `npm run start` and rerun that same command again.\n-   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!\n\n## Updating Existing Themes\n\nWhen new versions of `Create-React-WPTheme` are released, you can easily upgrade an existing theme using a single command.\n\n-   At a command prompt, navigate to your theme's `react-src` folder.\n    -   e.g. `\u003cYour Theme's Root Folder\u003e/react-src`\n-   If you use `npm` then run this command:\n    -   `npm install @devloco/react-scripts-wptheme@latest`\n-   If you use `yarn` then run this command:\n    -   `yarn add @devloco/react-scripts-wptheme@latest`\n\n### Updating TypeScript Types\n\nIf your theme uses TypeScript, you'll need to modify the theme's `react-app-env.d.ts` file:\n\n-   Navigate to the `\u003cYour Theme's Root Folder\u003e/react-src/src` folder.\n-   Open the `react-app-env.d.ts` file in your editor of choice.\n-   Change the line in there to read (be sure to include the leading three slashes):\n    -   `/// \u003creference types=\"@devloco/react-scripts-wptheme\" /\u003e`\n-   Save the change and you should be all set.\n\n## Developing Your Theme\n\n### React Tutorials\n\nIf you're looking at a React tutorial on the web, you can use `create-react-wptheme` in place of `create-react-app`.\n\u003cbr\u003eBut you do have to remember that the React app code is one extra folder down inside your theme folder.\n\u003cbr\u003eNotice that the final folder in this path is `react-src`:\n\n`/xampp/htdocs/wordpress/wp-content/themes/\u003cYour Theme's Root Folder\u003e/react-src`\n\nSo for example, if the tutorial instructs you to edit the `src/App.js` file, then for you, that file would actually be located at:\n\n`\u003cYour Theme's Root Folder\u003e/react-src/src/App.js`\n\n### The Public Folder\n\nThe 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.\n\nBut 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.\n\n**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.\n\n### Dev Configuration\n\nAfter 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.\n\n### HTTPS/SSL Support\n\nIf 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).\n\nTo configure the `Browser Refresh Server` to use SSL, follow these steps:\n\n-   Assuming you've already created a theme using `create-react-wptheme`, change directory into the `react-src` folder in your theme's folder\n    -   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.\n    -   Windows example: `cd C:\\xampp\\htdocs\\wordpress\\wp-content\\themes\\\u003cYour Theme's Root Folder\u003e\\react-src`\n    -   Mac or \\*nix example: `cd /xampp/htdocs/wordpress/wp-content/themes/\u003cYour Theme's Root Folder\u003e/react-src`\n-   Create a new folder to hold you're development SSL certificate and key.\n    -   All OSes: `mkdir ssl`\n-   Change directory into the `ssl` folder\n    -   All OSes `cd ssl`\n-   Then create the SSL certificate and key.\n    -   Windows: Install the [Linux Subsystem for Windows 10](https://docs.microsoft.com/en-us/windows/wsl/install-win10), then use the \\*nix instructions below.\n    -   Mac, see here: https://ksearch.wordpress.com/2017/08/22/generate-and-import-a-self-signed-ssl-certificate-on-mac-osx-sierra/\n    -   \\*nix, see here (**also works with Linux Subsystem for Windows 10**): https://stackoverflow.com/questions/10175812/how-to-create-a-self-signed-certificate-with-openssl\n-   Depending on which process you use to create the certificate and key, the files you created might have different extensions than those mentioned below.\n    -   That's OK.\n    -   Sometimes both files have a `.pem` extension, or each file has a different extension like `.crt` and `.key`.\n    -   **Just be sure you know which file is the certificate and which is the key.**\n-   There is a file named `user.dev.json` in the folder named `react-src` in your theme.\n    -   Open that file in your favorite text editor.\n    -   Change the \"wpThemeServer\" section to look like this (make sure it is proper JSON):\n    -   `\"wpThemeServer\": { \"enable\": true, \"host\": \"127.0.0.1\", \"port\": 8090, \"sslCert\": \"ssl/localhost.crt\", \"sslKey\": \"ssl/localhost.key\", \"watchFile\": \"../index.php\" },`\n    -   **NOTE** the `sslCert` and `sslKey` items. **Make sure the values point to your SSL certificate and key files.**\n    -   The paths to those files can be **full paths** or **relative paths** from the `react-src` folder (as shown above).\n    -   I like to set the `host` to `127.0.0.1` instead of \"localhost\". Supposedly the numeric address gets special treatment at the OS level as being mostly safe.\n-   Back in your command prompt, change dir back to the `react-src` folder.\n    -   All OSes: `cd ..`\n-   Start Node/Webpack JS watcher as you normally would:\n    -   All OSes: `npm run start`\n    -   Your theme should open in a new browser tab\n-   If you need to add an SSL exception to your browser for your new certificate, there is a page running over HTTPS at the \"host\" and \"port\" you set in `user.dev.json` above.\n    -   For example, if you're using host `127.0.0.1` and port `8090` as shown above, then open your browser to:\n        -   https\u003cnolink\u003e://127.0.0.1:8090/\n    -   From there you'll get the standard browser warning about self-signed certificates and get the option to add an exception.\n    -   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`.\n\n## Deploying Your Theme\n\nWhile 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.\n\nOpen a command prompt and change into the `react-src` folder of you theme and run this command:\n`npm run build`\n\nWhen that command finishes, your optimized files are located in a folder that can be deployed to your production server.\n\nHere's an example showing which folder to deploy to your server:\n\n-   ...wp-content\n    -   themes\n        -   my-theme\n            -   my-theme `\u003c- deploy this folder to your production server's themes folder`\n            -   react-src\n            -   !READY_TO_DEPLOY!.txt\n\nIf you need to continue developing your theme, simply:\n\n-   `cd react-src`\n-   `npm run start`\n\nAnd all your theme files will reappear.\n\n### Dealing With Differing Paths Between DEV and PROD\n\nThe `react-src/user.prod.json` configuration file is read when you run `npm run build`. The only option in there is setting the \"homepage\"\nwhich 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).\n\nDuring 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.\n\nFor example:\n\n-   Your WordPress dev server is running at http\u003cnolink\u003e://localhost/wordpress\n    -   the homepage setting in your main package.json file will probably work just fine.\n    -   The homepage line in your main package.json will be something like: `\"homepage\": \"/wordpress/wp-content/themes/\u003cYour Theme's Root Folder\u003e\"`\n-   But you know that your production server runs WordPress from the root: http\u003cnolink\u003e://mycoolblog.com/\n    -   In this case you want to remove the `/wordpress` part, so set the \"homepage\" line in your `user.prod.json` file to:\n        `\"homepage\": \"/wp-content/themes/\u003cYour Theme's Root Folder\u003e\"`\n    -   Then run `npm run build`\n    -   **Note** at this point, **your theme will appear broken on your dev server**. But it should look as expected on your production server.\n\n## Goals\n\n-   Remove WebPackDevServer and use your WordPress dev server instead.\n    -   Also, do not proxy the WordPress server.\n    -   Thus removing CORS as a concern.\n-   Maintain feature parity(ish) with `create-react-app`\n-   Touch the original `react-scripts` as little as possible.\n    -   Add new files where possible.\n    -   This will make merges easier.\n\n## Acknowledgements\n\nI'm grateful to the authors of existing related projects for their ideas and collaboration:\n\n-   [create-react-app](https://github.com/facebook/create-react-app)\n\n    The original.\n\n-   [filewatcher-webpack-plugin](https://www.npmjs.com/package/filewatcher-webpack-plugin)\n\n    I used this as an example for writing my own plugin for watching changes to the create-react-app \"public\" folder.\n\n## License\n\nCreate React WP Theme is open source software [licensed as MIT](https://github.com/devloco/create-react-wptheme/blob/master/LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevloco%2Fcreate-react-wptheme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevloco%2Fcreate-react-wptheme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevloco%2Fcreate-react-wptheme/lists"}