{"id":13506695,"url":"https://github.com/northosts/wuxt","last_synced_at":"2025-04-05T05:06:00.090Z","repository":{"id":38523046,"uuid":"183387925","full_name":"northosts/wuxt","owner":"northosts","description":"Nuxt/WordPress development environment, combining the worlds biggest CMS with the most awesome front-end application framework yet.","archived":false,"fork":false,"pushed_at":"2021-07-21T04:36:25.000Z","size":14037,"stargazers_count":551,"open_issues_count":54,"forks_count":62,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-03-29T04:05:36.716Z","etag":null,"topics":["docker","docker-compose","jamstack","nuxt","nuxtjs","vue","vuejs","wordpress"],"latest_commit_sha":null,"homepage":"https://github.com/northosts/wuxt","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/northosts.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-25T08:12:26.000Z","updated_at":"2025-03-26T07:57:47.000Z","dependencies_parsed_at":"2022-09-04T19:23:16.753Z","dependency_job_id":null,"html_url":"https://github.com/northosts/wuxt","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northosts%2Fwuxt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northosts%2Fwuxt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northosts%2Fwuxt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/northosts%2Fwuxt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/northosts","download_url":"https://codeload.github.com/northosts/wuxt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289426,"owners_count":20914464,"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":["docker","docker-compose","jamstack","nuxt","nuxtjs","vue","vuejs","wordpress"],"created_at":"2024-08-01T01:00:55.626Z","updated_at":"2025-04-05T05:06:00.064Z","avatar_url":"https://github.com/northosts.png","language":"PHP","funding_links":[],"categories":["Uncategorized","PHP"],"sub_categories":["Uncategorized"],"readme":"![Wuxt logo](_assets/wuxt.png?raw=true \"Wuxt\")\n\n# Nuxt/WordPress development environment - Wuxt\n\n**Wuxt** combines **_WordPress_**, the worlds biggest CMS with **_nuxt.js_**,\nthe most awesome front-end application framework yet.\n\n- [Quick start](#quick)\n- [Introduction](#intro)\n- [Architecture](#env)  \n- [Getting started](#start)\n  - [Custom container configuration](#start-custom)\n  - [Setup WordPress](#setup-wp)\n  - [Setup Nuxt.js](#setup-nuxt)  \n- [Generate and Deploy](#deploy)\n- [WordPress Rest API endpoints](#ep)\n  - [Extensions to the API endpoints](#epp)\n    - [Front-page](#epp-front)\n    - [Menus](#epp-menu)\n    - [Slugs](#epp-slugs)\n    - [Meta queries](#epp-meta)\n    - [Taxonomy queries](#epp-tax)\n    - [Geo queries](#epp-geo)\n    - [Custom post types](#epp-cpt)\n- [Scripts](#scripts)\n  - [Working with the containers](#scripts-containers)\n    - [WP-CLI and yarn](#scripts-containers-tools)\n  - [Scaffolding](#scripts-scaffolding)\n- [Links](#links)\n- [Credits](#cred)\n\n## Quick start\n\u003ca name=\"quick\"/\u003e\n\n    git clone https://github.com/northosts/wuxt.git\n    cd wuxt\n    docker-compose up -d\n\n- [http://localhost:3080/install.php](http://localhost:3080/install.php) - Install WordPress\n- [http://localhost:3080/wp-admin/options-permalink.php](http://localhost:3080/wp-admin/options-permalink.php) - Set permalinks to *Post name*\n- [http://localhost:3080/wp-admin/themes.php](http://localhost:3080/wp-admin/themes.php) - Activate **wuxt**-theme\n- [http://localhost:3000](http://localhost:3000) - Done\n\n## Introduction\n\u003ca name=\"intro\"/\u003e\n\nThe goal of Wuxt is to provide a ready to use development environment, which makes the\nfull power of **_WordPress_** easily available to your front-end app. Included\nin Wuxt are:\n\n-   Fully dockerized **_WordPress_** and **_nuxt.js_** container configuration,\n    `docker-compose up -d` sets up everything needed in one command and you can\n    start working\n\n-   Extended Rest API to give the front-end easy access to meta-fields,\n    featured media menus or the front-page configuration.\n\n-   The newest **_nuxt.js_** version, extended with a WordPress `$wp` object, to\n    connect to the extended **_WordPress_** Rest API.\n\nAll together the **Wuxt** features get you started with your front-end with just\none command, you just need to work with the intuitive WordPress admin interface\nand can skip all back-end coding. But if you know your way around\n**_WordPress_** you are able to easily extend the back-end as well.\n\n## The WUXT architecture\n\u003ca name=\"env\"/\u003e\n\n![WUXT environment](_assets/wuxt-env.png?raw=true \"WUXT environment\")\n\n## Getting started\n\u003ca name=\"start\"/\u003e\n\nFirst clone this repository to a directory you want, then change to that\ndirectory and simply start your containers (you need to have a running\n**_Docker_** installation of course):\n\n    docker-compose up -d\n\nThat starts the following containers:\n\n-   **_MySql_** (`mysql.wuxt`) Database for your **_WordPress_** installation. The data-folder\n    of the database-container is mirrored to the \\_db-folder of your host system, to\n    keep the data persistent.\n\n-   **_WordPress_** (`wp.wuxt`) on a **_Apache_** server with the newest **_PHP_** version and\n    the **Wuxt** Rest API extension theme, **_ACF_** and other good-to-have plugins\n    pre-installed. The wp-content directory of the **_WordPress_** directory is\n    mirrored to the wp-content directory on your host.\n\n-   **_nuxt.js_** (`front.wuxt`) started in development mode with file-monitoring and\n    browser-sync and extended by a complete **_WordPress_** Rest API wrapper and a\n    starter application, mimicing base functions of a **_WordPress_** theme.\n\nYour containers are available at\n\n-   front-end: `http://localhost:3000`\n-   back-end: `http://localhost:3080`, `http://localhost:3080/wp-admin`\n-   database: `docker exec -ti mysql.wuxt bash`\n\n### Starting with custom container configuration\n\u003ca name=\"start-custom\"/\u003e\n\n**wuxt** allows you to change the above setup to run multiple projects at the\nsame time or to adjust to your own environment. To change ports and container\nnames, add an `.env` file in the same directory of your `docker-compose.yml`\nfile. You can adjust the following values:\n\n    WUXT_PORT_FRONTEND=3000\n    WUXT_PORT_BACKEND=3080\n    WUXT_PORT_DIST=8080\n    WUXT_MYSQL_CONTAINER=mysql.wuxt\n    WUXT_WP_CONTAINER=wp.wuxt\n    WUXT_NUXT_CONTAINER=front.wuxt\n\nAfter you created the file, run\n\n    docker-compose down\n    docker-compose up -d\n\nThere is even a script that does everything to you :\n\n    npm run env\n\nYou will be asked for projectname, front-end-port, back-end-port and dist-port.\nThe script creates an `.env` file like the folllowing and stops the old containers:\n\n    WUXT_PORT_FRONTEND=4000\n    WUXT_PORT_BACKEND=4080\n    WUXT_PORT_DIST=9080\n    WUXT_MYSQL_CONTAINER=mysql.projectname\n    WUXT_WP_CONTAINER=wp.projectname\n    WUXT_NUXT_CONTAINER=front.projectname\n\nAfter running the script start the new containers\n\n    docker-compose up -d\n\n### Setup **_WordPress_**\n\u003ca name=\"setup-wp\"/\u003e\n\nIn short:\n\n- Install WordPress (`http://localhost:3080/install.php`)\n- Set permalinks to *Post name* (`http://localhost:3080/wp-admin/options-permalink.php`)\n- Activate **wuxt**-theme (`http://localhost:3080/wp-admin/themes.php`)\n\nDo a common **_WordPress_** installation at\n`http://localhost:3080/install.php`, then login to wp-admin and select the\n**wuxt** theme to activate all the API extensions. Additionally you might want\nto activate the **_ACF_** plugin to make your meta-value work easier. Last but\nnot least you have to set the permalink structure to \"Post Name\" in the\n**_WordPress_** settings.\n\nTo check if everything is running, visit `http://localhost:3080` and verify\nthat the **wuxt** info screen is showing.\n\nThen check that the Rest API at `http://localhost:3080/wp-json` is returning\na JSON-object you are good to go.\n\n### Setup **_nuxt.js_**\n\u003ca name=\"setup-nuxt\"/\u003e\n\nNuxt should have been started automatically inside the docker container. The\ncommand we use for running the **_nuxt.js_** server is `yarn dev`. Check\nif the front-end is running by opening `http://localhost:3000`. You should\nbe greeted by the **Wuxt** intro-screen.\n\nCheck if **_BrowserSync_** is running, by doing a minor change to the\nfront-page. The change should directly be visible on the front-page without manually reloading the page.\n\n## Generate and Deploy\n\u003ca name=\"deploy\"/\u003e\n\nTo make a complete deploy of WUXT, you have to get at least one server and solve\na lot of configuration stuff to get **_WordPress_**, **_MySql_** and **_nuxt.js_**\nrunning (we are working on a manual for some of the big cloud services).\n\nHowever, there is an easier solution, at least without on-site user generated\ncontent, like **_WordPress_**-comments (**_disqus_** would be ok, though). We\nhave tweaked the **_nuxt.js_** *generate*-command, so that you can generate a\nfully static site with all your content, posts and pages inside the `dist`\ndirectory of **_nuxt_**. Then it's only a matter of getting the static html-site\nuploaded to a webspace of your choice.\n\n### Generating a fully static site\n\nFirst be sure your containers are running\n\n    docker-compose up -d\n\nThen go to the wuxt root-directory and run *generate* with yarn\n\n    yarn generate\n\nDespite generating your static site, this commands runs some `docker-compose`\naction, so while generating, your WUXT site will be down and started again\nafter.\n\nAfter the generation there will be started a small local web-server, which deploys\nthe static site on\n\n    http://localhost:8080\n\nTo get the files you go to the `dist` directory inside your `wuxt/nuxt` directory:\n\n    wuxt/nuxt/dist\n\nTo shut down the local web-server you have to run the following command insie the\n`wuxt` directory:\n\n    docker-compose -f dist.yml down\n\n### How it works\n\nThe *generate*-command simply scrapes all available urls you added to your\n**_nuxt.js_** and **_WordPress_** installation, saves the html-output and caches\nthe JSON-requests to the **_WordPress_** Rest API.\n\nTo know which urls are available, the generate command asks the **_WordPress_**\nRest API for a list of existing endpoints and all links used in the\n**_WordPress_** menus. You can view that list with the following endpoint:\n\n    GET: /wp-json/wuxt/v1/generate\n\nSince **_nuxt.js_** doesn't fully support 100% static sites yet, we have to get\nhelp of the `static` plugin used on **_nuxt.org_**, which is jsut taking care\nof the payload caching. Read more [here](https://github.com/nuxt/rfcs/issues/22)\nand [here](https://github.com/nuxt/nuxtjs.org/tree/master/modules/static).\n\n\n## WordPress Rest API endpoints\n\u003ca name=\"ep\"/\u003e\n\nThe **_WordPress_** Rest API gives you access to a wide range of native\nendpoints. Find the docs at: [https://developer.wordpress.org/rest-api/reference/](https://developer.wordpress.org/rest-api/reference/). To easily access the\nendpoints from **_nuxt.js_** you can use the `$wp` extension, which integrates\nthe [node-wpapi](https://www.npmjs.com/package/node-wp) library. You can find the full documentation [here](https://github.com/WP-API/node-wpapi).\n\n### Extensions to the API endpoints\n\u003ca name=\"epp\"/\u003e\n\nTo make **wuxt** even more easy to use, there are a bunch of endpoint extensions to the **_WordPress_** Rest API.\n\n#### Front-page\n\u003ca name=\"epp-front\"/\u003e\n\n```\n$wp.frontPage()\n$wp.frontPage().embed()\n```\n\nor\n\n```\nGET: /wp-json/wuxt/v1/front-page\nGET: /wp-json/wuxt/v1/front-page?_embed\n```\n\nYou can use the **_WordPress_** front-page settings to build your front-ends\nfirst page. If you setup the front-page in **_WordPress_** as static page, the\nendpoint will return the corresponing page object.\n\nIf there is no front-page configured, the query automatically returns the\nresult of the default posts query\n\n`GET` `/wp-json/wp/v2/posts`\n\nNote that the `_embed` parameter works for the front-page query, which gives you\naccess to featured media (post-thumbnails), author information and more.\n\n#### Menus\n\u003ca name=\"epp-menu\"/\u003e\n\n```\n$wp.menu()\n$wp.menu().location(\u003clocation\u003e)\n```\n\nor\n\n```\nGET: /wp-json/wuxt/v1/menu\nGET: /wp-json/wuxt/v1/menu?location=\u003clocation\u003e\n```\n\nThe **_WordPress_** Rest API is not providing an endpoint for menus by default,\nso we added one. We have also registered a standard menu with the location `main`,\nwhich is returned as complete menu-tree, when you request the endpoint without\nparameters.\n\nDon't forget to create a menu and adding it to a location in `wp-admin` when you\nwant to use this endpoint.\n\nIf you want to use multiple menus, you can request them by providing the menu\nlocation to the endpoint.\n\n#### Slugs\n\u003ca name=\"epp-slugs\"/\u003e\n\n```\n$wp.slug().name('\u003cpost-or-page-slug\u003e')\n$wp.slug().name('\u003cpost-or-page-slug\u003e').embed()\n```\n\nor\n\n```\nGET: /wp-json/wuxt/v1/slug/\u003cpost-or-page-slug\u003e\nGET: /wp-json/wuxt/v1/slug/\u003cpost-or-page-slug\u003e?_embed\n```\n\nThe **_WordPress_** Rest API is not providing an endpoint to get posts or pages\nby slug. That doesn't mirror the **_WordPress_** theme default behaviour,\nwhere the url-slug can point to both a page or a post.\n\nWith the `slug` endpoint we add that function, which is first looking for a post\nwith the given slug and then for a page. The `embed` parameter is working for\nthe `slug` endpoint.\n\n#### Meta fields\n\u003ca name=\"epp-meta\"/\u003e\n\nThe **_WordPress_** Rest API does not include meta fields in the post objects by\ndefault. For two of the most common plugins, ACF and Yoast WordPress SEO, we\nhave automatically added the values of these fields. They are located in the\n`meta` section of the response objects.\n\n#### Taxonomy queries\n\u003ca name=\"epp-tax\"/\u003e\n\nTaxonomy queries are limited of the simple WordPress Rest API url structure.\nEspecially with filtering queries, we struggled with the missing relation\nparameter in queries for posts by taxonomy. We added this feature with a new\nparameter to the WordPress API:\n\n```\nGET: /wp-json/wp/v2/posts/?categories=1,2\u0026and=true\n```\n\n***Note:*** *Setting the relation to \"and\" will cause all taxonomy queries to\nuse it. Right now you cant query one taxonomy with \"and\" and another with \"or\".*\n\nIn Nuxt you just have to use the \"and\" param after a post query for categories.\n\n```\n$wp.posts().categories([1,2]).param('and', true)\n```\n\n#### Geo Queries\n\u003ca name=\"epp-geo\"/\u003e\n\nIf your application has to get posts by geographical proximity, you can use the geo parameters.\n\n    GET /wp-json/wp/v2/posts/?coordinates=\u003clat\u003e,\u003clng\u003e\u0026distance=\u003cdistance\u003e\n\nThe coordinates parameter has to contain lat and lng, comma-separated and each value can be prefixed with the meta-key if has to be compared with (default keys: `lat`, `lng`). The distance is calculated in kilometers, postfix the value with **m** for miles. Some example queries:\n\n     GET /wp-json/wp/v2/posts/?coordinates=52.585,13.373\u0026distance=10\n     GET /wp-json/wp/v2/posts/?coordinates=lat_mkey:52.585,lng_mkey:13.373\u0026distance=10\n     GET /wp-json/wp/v2/posts/?coordinates=52.585,13.373\u0026distance=10m\n\n\n#### Custom post types\n\u003ca name=\"epp-cpt\"/\u003e\n\nThe ***WordPress*** Rest API is providing endpoints for custom post types, as\nlong as they are registered the right way (see the *Scaffolding* section for generating cpt-definitions).\n\nTo make querying of your custom post types as easy as everything else, we added the `cpt` method to the `$wp` object. See post type queries for a\nfictional 'Movies' post type, below\n\n```\n$wp.cpt('movies')\n$wp.cpt('movies').id( 7 )\n```\n\nThe `cpt` function returns cpt-objects similar to the `posts()` or `pages()`\nqueries, meta fields are included.\n\n## Scripts\n\u003ca name=\"scripts\"/\u003e\n\nTo help you with some of the common tasks in **wuxt**, we integrated a bunch of\n**npm** scripts. Just install the needed packages in the root directory and you\nare ready to run.\n\n    npm install\n\n### Working with the containers\n\u003ca name=\"scripts-containers\"/\u003e\n\nWorking with ***Docker*** is awesome, but has some drawbacks. One of them is\nthat you have to make some changes from inside the container. To\nenter the **WUXT** containers, you can use the following ***npm***\nscripts:\n\n    npm run enter:mysql\n    npm run enter:wp\n    npm run enter:front\n\nYou exit a container with `exit`.\n\n#### WP-CLI and yarn\n\u003ca name=\"scripts-containers-tools\"/\u003e\n\nTwo of the most\ncommon tasks are managing ***WordPress*** and installing new packages\nin the front-end.\n\n**WUXT** provides you with the full power of the\n***WP-CLI*** tool. Check out all documentation at [https://developer.wordpress.org/cli/commands/](https://developer.wordpress.org/cli/commands/). To run any ***WP-CLI*** command inside the `wp.wuxt`\ncontainer, just use the following ***npm***-script:\n\n    npm run wp \u003cwp-cli-command\u003e\n\nExamples: `npm run wp plugin list`, `npm run wp plugin install advanced-custom-fields`, `npm run wp user create wuxt me@wuxt.io`\n\nThe same concept we use for ***yarn*** in the front container:\n\n    npm run yarn \u003cyarn-command\u003e\n\nExample: `npm run yarn add nuxt-webfontloader`\n\nThe commands are checking if the containers are running and installing needed\ndependencies automatically. So if ***WP-CLI*** is not installed in the container it will be installed before running a `wp` command.\n\n### Scaffolding\n\u003ca name=\"scripts-scaffolding\"/\u003e\n\n**WUXT** allows you to generate custom post types and taxonomies via ***npm***\nscripts. You can pass needed parameters as arguments. If you don't pass\narguments, you will get prompted.\n\n**Scaffolding a post type**\n\n    npm run scaffold:cpt \u003cname\u003e\n\n    # Examples:\n    npm run scaffold:cpt\n    npm run scaffold:cpt Movie\n\nThe custom post type definition is copied into the `cpts` folder of the wuxt\ntheme and loaded automatically by the theme.\n\nTo query the new post-type you can use the `cpt` method of the **wuxt** `$wp` object.\n\n**Scaffolding a taxonomy**\n\n    npm run scaffold:tax \u003cname\u003e \u003cpost-types\u003e\n\n    # Examples:\n    npm run scaffold:tax\n    npm run scaffold:tax Venue event,cafe\n\nThe taxonomy definition is copied into the `taxonomies` folder of the wuxt\ntheme and loaded automatically by the theme.\n\n## Links\n\u003ca name=\"links\"/\u003e\n\n[WUXT Headless WordPress API Extensions](https://wordpress.org/plugins/wuxt-headless-wp-api-extensions/): Plugin which includes all our API extensions.\n\n[Nuxt + WordPress = WUXT](https://www.danielauener.com/nuxt-js-wordpress-wuxt/): Introduction post for WUXT.\n\n## Credits\n\u003ca name=\"cred\"/\u003e\n\n[@yashha](https://github.com/yashha/wp-nuxt/commits?author=yashha) for the excelent idea with the `$wp` object, first implemented in [https://github.com/yashha/wp-nuxt](https://github.com/yashha/wp-nuxt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorthosts%2Fwuxt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnorthosts%2Fwuxt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorthosts%2Fwuxt/lists"}