diff --git a/.circleci/config.yml b/.circleci/config.yml deleted file mode 100644 index 27d116c1d..000000000 --- a/.circleci/config.yml +++ /dev/null @@ -1,263 +0,0 @@ -# PHP CircleCI 2.0 configuration file -# -# Check https://circleci.com/docs/2.0/language-php/ for more details -# -version: 2.1 -orbs: - wp-product-orb: wpengine/wp-product-orb@1.3.0 - php: circleci/php@1.1.0 - node: circleci/node@4.1.0 - -jobs: - checkout: - executor: wp-product-orb/default - steps: - - checkout - - persist_to_workspace: - root: . - paths: - - . - - plugin-checkout: - executor: wp-product-orb/default - working_directory: ~/project/plugins/<> - environment: - WPE_SESSION_DIR: ./.wpe - parameters: - slug: - type: string - filename: - type: string - steps: - - attach_workspace: - at: ~/project - - run: - name: Make artifacts build directory - command: | - [ ! -d "build" ] && mkdir build &>/dev/null - - wp-product-orb/get-version-from-php: - filename: <> - return_var: BUILD_VERSION - - wp-product-orb/variable: - var: BUILD_VERSION - value: $BUILD_VERSION - - persist_to_workspace: - root: ~/project - paths: - - plugins/<> - - plugin-composer: - executor: php/default - working_directory: ~/project/plugins/<> - parameters: - slug: - type: string - steps: - - attach_workspace: - at: ~/project - - php/install-composer - - php/install-packages: - app-dir: . - - run: - name: Composer PHP lint and code sniffer - command: | - /usr/local/bin/composer lint && /usr/local/bin/composer phpcs - rm -v composer-setup.php - working_directory: . - - persist_to_workspace: - root: ~/project - paths: - - plugins/<> - - plugin-test: - working_directory: ~/project/plugins/<> - docker: - - image: cimg/php:7.4 - - image: circleci/mysql:5.7 - environment: - MYSQL_DATABASE: wp_database - MYSQL_USER: wp_user - MYSQL_PASSWORD: wp_pass - MYSQL_ROOT_PASSWORD: password - parameters: - slug: - type: string - steps: - - attach_workspace: - at: ~/project - - php/install-composer - - php/install-packages: - app-dir: . - - run: - name: Install Subversion package - command: | - sudo apt-get update -yq - sudo apt-get install subversion -yq - - run: - name: Setup WordPress testing framework - command: | - /bin/bash tests/install-wp-tests.sh wp_database wp_user wp_pass 127.0.0.1 latest true - working_directory: . - - run: - name: Run testing suite - command: | - composer test - working_directory: . - - plugin-bundle-zip: - executor: wp-product-orb/default - working_directory: ~/project/plugins/<> - environment: - WPE_SESSION_DIR: ./.wpe - parameters: - slug: - type: string - steps: - - attach_workspace: - at: ~/project - - wp-product-orb/variable-load - - run: - name: "Bundle plugin files into a zip" - command: | - cd .. - zip --verbose -x@<>/.zipignore -x *.wpe/* */build/ -r "<>/build/<>.$BUILD_VERSION.zip" <> - - store_artifacts: - path: build - - persist_to_workspace: - root: ~/project - paths: - - plugins/<>/build - - plugin-bundle-json: - executor: wp-product-orb/parser - working_directory: ~/project/plugins/<> - environment: - WPE_SESSION_DIR: ./.wpe - parameters: - slug: - type: string - steps: - - attach_workspace: - at: ~/project - - wp-product-orb/variable-load - - wp-product-orb/parse-wp-readme: - infile: readme.txt - outfile: build/<>.$BUILD_VERSION.json - - store_artifacts: - path: build - - persist_to_workspace: - root: ~/project - paths: - - plugins/<>/build - - plugin-deploy: - executor: wp-product-orb/authenticate - working_directory: ~/project/plugins/<> - environment: - WPE_SESSION_DIR: ./.wpe - parameters: - auth_url: - type: string - upload_url: - type: string - slug: - type: string - steps: - - attach_workspace: - at: ~/project - - wp-product-orb/variable-load - - wp-product-orb/authenticate: - user: WPE_LDAP_USER - pass: WPE_LDAP_PASS - url: <> - - wp-product-orb/post-zip: - url: <>/<> - zip: build/<>.$BUILD_VERSION.zip - json: build/<>.$BUILD_VERSION.json - version: $BUILD_VERSION - -workflows: - # Workflows defined for each package and plugin. - # tag example for deploying an update for wpe-headless: plugin/wpe-headless/1.0.0 - plugin-wpe-headless: - jobs: - - checkout: - filters: - tags: - only: /.*/ - - plugin-checkout: - name: plugin-checkout-wpe-headless - slug: wpe-headless - filename: wpe-headless.php - requires: - - checkout - # Enable running this job when a tag is published - filters: - tags: - only: /.*/ - - plugin-composer: - name: plugin-composer-wpe-headless - slug: wpe-headless - requires: - - plugin-checkout-wpe-headless - # Enable running this job when a tag is published - filters: - tags: - only: /.*/ - - plugin-test: - name: plugin-test-wpe-headless - slug: wpe-headless - requires: - - plugin-composer-wpe-headless - # Enable running this job when a tag is published - filters: - tags: - only: /.*/ - - plugin-bundle-zip: - name: plugin-bundle-zip-wpe-headless - slug: wpe-headless - requires: - - plugin-test-wpe-headless - # Run this job on every commit/PR so the plugin is available as a build artifact - filters: - tags: - only: /.*/ - - plugin-bundle-json: - name: plugin-bundle-json-wpe-headless - slug: wpe-headless - requires: - - plugin-test-wpe-headless - # Run this job on every commit/PR to make sure it's in working order prior to deploying - filters: - tags: - only: /.*/ - - plugin-deploy: - name: "Deploy zip to api (staging) wpe-headless" - slug: wpe-headless - requires: - - plugin-bundle-zip-wpe-headless - - plugin-bundle-json-wpe-headless - filters: - branches: - only: - - main - - canary - tags: - only: /.*/ - context: wpe-ldap-creds - auth_url: https://auth-staging.wpengine.io/v1/tokens - upload_url: https://wp-product-info-staging.wpesvc.net/v1/plugins - - plugin-deploy: - name: "Deploy zip to api (production) wpe-headless" - slug: wpe-headless - requires: - - "Deploy zip to api (staging) wpe-headless" - filters: - branches: - ignore: /.*/ - tags: - # tag ex. plugin/wpe-headless/1.0.0 - only: /^plugin\/wpe-headless\/\S+/ - context: wpe-ldap-creds - auth_url: https://auth.wpengine.io/v1/tokens - upload_url: https://wp-product-info.wpesvc.net/v1/plugins diff --git a/.github/actions/release-plugin/action.yml b/.github/actions/release-plugin/action.yml new file mode 100644 index 000000000..8655a8c68 --- /dev/null +++ b/.github/actions/release-plugin/action.yml @@ -0,0 +1,22 @@ +name: 'WordPress Plugin Deploy' +description: 'Deploy to the WordPress Plugin Repository' +author: '10up' +branding: + icon: 'upload-cloud' + color: 'blue' +inputs: + generate-zip: + description: 'Generate package zip file?' + default: false +outputs: + zip-path: + description: 'Path to zip file' + value: ${{ steps.deploy.outputs.zip-path }} +runs: + using: 'composite' + steps: + - id: deploy + env: + INPUT_GENERATE_ZIP: ${{ inputs.generate-zip }} + run: ${{ github.action_path }}/deploy.sh + shell: bash diff --git a/.github/actions/release-plugin/deploy.sh b/.github/actions/release-plugin/deploy.sh new file mode 100644 index 000000000..e036df933 --- /dev/null +++ b/.github/actions/release-plugin/deploy.sh @@ -0,0 +1,108 @@ +#!/bin/bash + +# Note that this does not use pipefail +# because if the grep later doesn't match any deleted files, +# which is likely the majority case, +# it does not exit with a 0, and I only care about the final exit. +set -eo + +# Ensure SVN username and password are set +# IMPORTANT: while secrets are encrypted and not viewable in the GitHub UI, +# they are by necessity provided as plaintext in the context of the Action, +# so do not echo or use debug mode unless you want your secrets exposed! +if [[ -z "$SVN_USERNAME" ]]; then + echo "Set the SVN_USERNAME secret" + exit 1 +fi + +if [[ -z "$SVN_PASSWORD" ]]; then + echo "Set the SVN_PASSWORD secret" + exit 1 +fi + +# Require the PLUGIN_DIR environment variable to be set +if [[ -z "$PLUGIN_DIR" ]]; then + echo "Set the PLUGIN_DIR environment variable" + exit 1 +fi +echo "ℹ︎ PLUGIN_DIR is $PLUGIN_DIR" + +# Allow some ENV variables to be customized +if [[ -z "$SLUG" ]]; then + SLUG=${GITHUB_REPOSITORY#*/} +fi +echo "ℹ︎ SLUG is $SLUG" + +# Does it even make sense for VERSION to be editable in a workflow definition? +if [[ -z "$VERSION" ]]; then + VERSION="${GITHUB_REF#refs/tags/}" + VERSION="${VERSION#v}" +fi +echo "ℹ︎ VERSION is $VERSION" + +if [[ -z "$ASSETS_DIR" ]]; then + ASSETS_DIR=".wordpress-org" +fi +echo "ℹ︎ ASSETS_DIR is $ASSETS_DIR" + +SVN_URL="https://plugins.svn.wordpress.org/${SLUG}/" +SVN_DIR="${HOME}/svn-${SLUG}" + +# Checkout just trunk and assets for efficiency +# Tagging will be handled on the SVN level +echo "➤ Checking out .org repository..." +svn checkout --depth immediates "$SVN_URL" "$SVN_DIR" +cd "$SVN_DIR" +svn update --set-depth infinity assets +svn update --set-depth infinity trunk + +echo "➤ Copying files..." +if [[ -e "$GITHUB_WORKSPACE/$PLUGIN_DIR/.distignore" ]]; then + echo "ℹ︎ Using .distignore" + # Copy from PLUGIN_DIR to /trunk, excluding dotorg assets + # The --delete flag will delete anything in destination that no longer exists in source + rsync -rc --exclude-from="$GITHUB_WORKSPACE/$PLUGIN_DIR/.distignore" "$GITHUB_WORKSPACE/$PLUGIN_DIR" trunk/ --delete --delete-excluded +else + rsync -rc "$GITHUB_WORKSPACE/$PLUGIN_DIR" trunk --delete --delete-excluded +fi + +# Copy dotorg assets to /assets +if [[ -d "$GITHUB_WORKSPACE/$PLUGIN_DIR/$ASSETS_DIR/" ]]; then + rsync -rc "$GITHUB_WORKSPACE/$PLUGIN_DIR/$ASSETS_DIR/" assets/ --delete +else + echo "ℹ︎ No assets directory found; skipping asset copy" +fi + +# Add everything and commit to SVN +# The force flag ensures we recurse into subdirectories even if they are already added +# Suppress stdout in favor of svn status later for readability +echo "➤ Preparing files..." +svn add . --force > /dev/null + +# SVN delete all deleted files +# Also suppress stdout here +svn status | grep '^\!' | sed 's/! *//' | xargs -I% svn rm %@ > /dev/null + +# Copy tag locally to make this a single commit +echo "➤ Copying tag..." +svn cp "trunk" "tags/$VERSION" + +# Fix screenshots getting force downloaded when clicking them +# https://developer.wordpress.org/plugins/wordpress-org/plugin-assets/ +svn propset svn:mime-type image/png assets/*.png || true +svn propset svn:mime-type image/jpeg assets/*.jpg || true + +svn status + +echo "➤ Committing files..." +svn commit -m "Update to version $VERSION from GitHub" --no-auth-cache --non-interactive --username "$SVN_USERNAME" --password "$SVN_PASSWORD" + +if $INPUT_GENERATE_ZIP; then + echo "Generating zip file..." + cd "$SVN_DIR/trunk" || exit + zip -r "${GITHUB_WORKSPACE}/${PLUGIN_DIR}/${SLUG}.zip" . + echo "::set-output name=zip-path::${GITHUB_WORKSPACE}/${PLUGIN_DIR}/${SLUG}.zip" + echo "✓ Zip file generated!" +fi + +echo "✓ Plugin deployed!" diff --git a/.github/workflows/e2e-test-plugin.yml b/.github/workflows/e2e-test-plugin.yml new file mode 100644 index 000000000..d25ff8b8b --- /dev/null +++ b/.github/workflows/e2e-test-plugin.yml @@ -0,0 +1,53 @@ +name: E2E Test Plugin +on: pull_request +jobs: + e2e_test_plugin: + timeout-minutes: 10 + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v2 + - name: Setup Node + uses: actions/setup-node@v2 + with: + node-version: '16' + - name: Install NPM Deps + run: | + rm package-lock.json + npm install + npm run build + - name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + php-version: '7.4' + - name: Setup Frontend + run: | + NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8080 WP_HEADLESS_SECRET=00000000-0000-0000-0000-000000000001 npm run dev:next:getting-started & + - name: Composer install + working-directory: plugins/faustwp + run: composer install + - name: Setup Containers + working-directory: plugins/faustwp + run: docker-compose up -d + - name: Sleep 15 seconds + run: sleep 15 + - name: Install WP GraphQL + working-directory: plugins/faustwp + run: | + docker exec --workdir=/var/www/html/wp-content/plugins/faustwp $(docker-compose ps -q wordpress) wp plugin install wp-graphql --activate --allow-root + - name: Setup testing data + working-directory: plugins/faustwp + run: | + docker exec --workdir=/var/www/html/wp-content/plugins/faustwp $(docker-compose ps -q wordpress) wp db export tests/_data/dump.sql --allow-root + - name: Copy env file + working-directory: plugins/faustwp + run: cp .env.testing.example .env.testing + - name: Run test + working-directory: plugins/faustwp + run: vendor/bin/codecept run acceptance + - name: Upload Test Output + uses: actions/upload-artifact@v2 + if: failure() + with: + name: failed-test-output + path: ${{ github.workspace }}/plugins/faustwp/tests/_output diff --git a/.github/workflows/eslint.yml b/.github/workflows/lint-packages.yml similarity index 89% rename from .github/workflows/eslint.yml rename to .github/workflows/lint-packages.yml index fd12e5d24..4979bf123 100644 --- a/.github/workflows/eslint.yml +++ b/.github/workflows/lint-packages.yml @@ -1,7 +1,7 @@ -name: lint +name: Lint Packages on: pull_request jobs: - lint: + lint_packages: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 diff --git a/.github/workflows/lint-plugin.yml b/.github/workflows/lint-plugin.yml new file mode 100644 index 000000000..95389c329 --- /dev/null +++ b/.github/workflows/lint-plugin.yml @@ -0,0 +1,18 @@ +name: Lint Plugin +on: pull_request +jobs: + lint_plugin: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v2 + - name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + php-version: '7.3' + - name: Install Dependencies + working-directory: plugins/faustwp + run: composer install + - name: Run Lint + working-directory: plugins/faustwp + run: composer lint diff --git a/.github/workflows/release-plugin.yml b/.github/workflows/release-plugin.yml new file mode 100644 index 000000000..7045720f4 --- /dev/null +++ b/.github/workflows/release-plugin.yml @@ -0,0 +1,20 @@ +name: Deploy to WordPress.org +on: + push: + tags: + - "plugin/faustwp/*" +jobs: + release_plugin: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@master + - name: WordPress Plugin Deploy + # Use a variant of 10up/action-wordpress-plugin-deploy that allows us to specify a PLUGIN_DIR + # to support our monorepo structure. + uses: ./.github/actions/release-plugin + env: + SVN_PASSWORD: ${{ secrets.SVN_PASSWORD }} + SVN_USERNAME: ${{ secrets.SVN_USERNAME }} + PLUGIN_DIR: plugins/faustwp + SLUG: faustwp diff --git a/.github/workflows/test.yml b/.github/workflows/test-packages.yml similarity index 89% rename from .github/workflows/test.yml rename to .github/workflows/test-packages.yml index 4d305fe1f..c7caa8c31 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test-packages.yml @@ -1,7 +1,7 @@ -name: test +name: Test Packages on: pull_request jobs: - test: + test_packages: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 diff --git a/.github/workflows/test-plugin.yml b/.github/workflows/test-plugin.yml new file mode 100644 index 000000000..a2419afb1 --- /dev/null +++ b/.github/workflows/test-plugin.yml @@ -0,0 +1,19 @@ +name: Test Plugin +on: pull_request +jobs: + test_plugin: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v2 + - name: Create Docker Containers + working-directory: ./plugins/faustwp + run: docker-compose up -d + - name: Sleep 15 seconds + run: sleep 15 + - name: Setup testing framework + working-directory: ./plugins/faustwp + run: docker exec $(docker-compose ps -q wordpress) init-testing-environment.sh + - name: Run unit tests + working-directory: ./plugins/faustwp + run: docker exec -w /var/www/html/wp-content/plugins/faustwp $(docker-compose ps -q wordpress) composer test diff --git a/.wp-env.json b/.wp-env.json deleted file mode 100644 index 9d1a7873a..000000000 --- a/.wp-env.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "core": "WordPress/WordPress#5.6", - "phpVersion": "7.4", - "plugins": [ - "https://downloads.wordpress.org/plugin/wp-graphql.1.1.3.zip", - "./plugins/wpe-headless" - ] -} \ No newline at end of file diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 94de5bf28..380a3d340 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -30,19 +30,19 @@ As this is a monorepo, you will not be able to check out this repository into `w Instead, you can create symlinks to the themes/plugins in this repository. Best of all, this will also sync your work across multiple local sites! -#### WPE Headless Plugin +#### FaustWP Plugin **Setup** -To begin working with the WPE Headless WordPress plugin, you will need to symlink the plugin from the monorepo to your WordPress plugin development directory. +To begin working with the FaustWP WordPress plugin, you will need to symlink the plugin from the monorepo to your WordPress plugin development directory. ``` -ln -s /path/to/faustjs/plugins/wpe-headless /path/to/wordpress/wp-content/plugins/wpe-headless +ln -s /path/to/faustjs/plugins/faustwp /path/to/wordpress/wp-content/plugins/faustwp ``` **PHP Code Sniffer** [PHP Code Sniffer](https://github.com/squizlabs/PHP_CodeSniffer) is configured for the [WordPress code standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/). -Install the composer packages from within `wpe-headless` directory if you haven't already. +Install the composer packages from within `faustwp` directory if you haven't already. ``` composer install @@ -61,34 +61,29 @@ composer phpcs:fix ``` **WordPress Unit Tests** -To run WordPress unit tests, set up the test framework: -``` -/bin/bash /path/to/faustjs/plugins/wpe-headless/tests/install-wp-tests.sh wpe_headless_tests db_name db_password -``` - -If you connect to MySQL via a sock connection, you can run the following. +To run WordPress unit tests, first create the Docker containers from the `plugins/faustwp` directory: ``` -/bin/bash /path/to/faustjs/plugins/wpe-headless/tests/install-wp-tests.sh wpe_headless_tests db_name db_password localhost:/path/to/mysql/mysqld.sock +docker-compose up -d ``` -Install the composer packages from within `wpe-headless` directory if you haven't already. +Once the containers are up, set up the test framework: ``` -composer install +docker-compose exec wordpress init-testing-environment.sh ``` -Within the `wpe-headless` directory, run `phpunit` either directly or as a composer command: +Run the unit tests: ``` -vendor/bin/phpunit +docker-compose exec -w /var/www/html/wp-content/plugins/faustwp wordpress composer test ``` -or +Finally, to remove the containers: ``` -composer test +docker-compose down ``` ## End-2-End Testing @@ -110,6 +105,7 @@ Use [Codeception](https://codeception.com/) for running end-2-end tests in the b ### 2. Front-end Setup 1. Create the following `.env.test` in `examples/next/getting-started`. + ``` # Your WordPress site URL NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8080 @@ -117,17 +113,18 @@ NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8080 # Plugin secret found in WordPress Settings->Headless WP_HEADLESS_SECRET=00000000-0000-0000-0000-000000000001 ``` + 2. From within `examples/next/getting-started`, run `NODE_ENV=test npm run dev`. ### 3. WordPress Setup 1. Leave the node server running and open a new shell. -1. Move into the WPE Headless plugin directory `plugins/wpe-headless`. +1. Move into the FaustWP plugin directory `plugins/faustwp`. 1. Run `composer install` if you haven't already. 1. Prepare a test WordPress site. - 1. Run `docker-compose up -d --build`. If building for the first time, it could take some time to download and build the images. - 1. Run `docker-compose exec --workdir=/var/www/html/wp-content/plugins/wpe-headless --user=www-data wordpress wp plugin install wp-graphql --activate` - 1. Run `docker-compose exec --workdir=/var/www/html/wp-content/plugins/wpe-headless --user=www-data wordpress wp db export tests/_data/dump.sql` + 1. Run `docker-compose up -d --build`. If building for the first time, it could take some time to download and build the images. + 1. Run `docker-compose exec --workdir=/var/www/html/wp-content/plugins/faustwp --user=www-data wordpress wp plugin install wp-graphql --activate` + 1. Run `docker-compose exec --workdir=/var/www/html/wp-content/plugins/faustwp --user=www-data wordpress wp db export tests/_data/dump.sql` 1. Copy `.env.testing.example` to `.env.testing`. 1. Run `vendor/bin/codecept run acceptance` to start the end-2-end tests. @@ -142,26 +139,20 @@ WP_HEADLESS_SECRET=00000000-0000-0000-0000-000000000001 Developers with full GitHub repository access can create public releases: -### Release the wpe-headless plugin - -1. Update the `Version` in the file header at `plugins/wpe-headless/wpe-headless.php`. -2. Update the changelog and 'stable tag' in `plugins/wpe-headless/readme.txt`. -3. Commit and push your changes for review **(DO NOT MERGE YET)**. -4. Tag the approved commit with `plugin/wpe-headless/[version]`, for example: `git tag plugin/wpe-headless/0.3.5` and push the tag (`git push --tags`). Or use GitHub to [create a new release](https://github.com/wpengine/faustjs/releases/new) with that tag. This must be done prior to merging changes into the `canary` branch. -5. Merge your changes into the `canary` branch +### Release the FaustWP plugin -CircleCI will build and deploy the plugin zip. The latest version will be available here: - -`https://wp-product-info.wpesvc.net/v1/plugins/wpe-headless?download` +1. Update the `Version` in the file header at `plugins/faustwp/faustwp.php`. +2. Update the changelog and 'stable tag' in `plugins/faustwp/readme.txt`. +3. Commit and merge your changes into the `canary` branch. +4. Create a new release on GitHub with a tag of `plugin/faustwp/[version]`. This will kick off our GitHub Action to deploy the `faustwp` plugin to WordPress.org ### Release the @faustjs packages -1. From the monorepo root directory, run either `npm run patch` or `npm run minor`. This will increment all the packages' versions, keeping them in lockstep. -2. Remove `node_modules` and `package-lock.json` from the root directory. -3. Run `npm i && npm test` to verify that the packages are working. -4. Update the changelogs of the applicable packages. -5. Commit and push your changes for review. -6. Once reviewed and merged into `canary`, our GitHub Actions workflow will publish the packages to NPM. +We use [Changesets](https://github.com/atlassian/changesets) to automate our deployment process for the @faustjs packages. + +1. When you are ready to release the @faustjs packages, go to [pull requests](https://github.com/wpengine/faustjs/pulls), and view the "Release Packages" PR. +2. Review the changes and make sure that the packages are versioned appropriately, and that the changelogs reflect the changes accurately. +3. When ready to release, merge the PR into `canary`. This will kick off the GitHub Action to publish to NPM. Once deployed, the updated packages will be visible here: diff --git a/docs/next/guides/authentication.mdx b/docs/next/guides/authentication.mdx index 84186d846..071cd2ee4 100644 --- a/docs/next/guides/authentication.mdx +++ b/docs/next/guides/authentication.mdx @@ -44,7 +44,7 @@ Redirect based authentication is the default strategy in Faust.js. This strategy This strategy is great for use cases where your authenticated users are admins/editors/etc. and do not necessarily need a "white label" login/register experience. Typically, you would use the redirect strategy if your primary reason for authentication is previews. -Since Redirect based authentication is the default authentication method, there is no configuration needed on your end to use it. It comes out of the box, and you'll see it in action when using previews or the [`useAuth`](/docs/next/reference/custom-hooks#useauth) hook. +Since Redirect based authentication is the default authentication method, there is no configuration needed on your end to use it. It comes out of the box, and you'll see it in action when using previews or the [`useAuth`](/docs/next/reference/hooks/useAuth) hook. ### Local Based Authentication @@ -149,7 +149,7 @@ The `useLogin` hook exports an object with the following properties: - `data`: the response data from the login request. - `error`: the error from the login request. -For a more detailed explanation of the `useLogin` hook, see the [`useLogin` hook docs](/docs/next/reference/custom-hooks#uselogin) . +For a more detailed explanation of the `useLogin` hook, see the [`useLogin` hook docs](/docs/next/reference/hooks/useLogin) . Upon a successful login, a refresh token will be stored in a secure, http only cookie, as well as the access token in memory to use for subsequent authenticated requests. A login request can be confirmed it succeeded by checking for the `code` property in the `data` object. @@ -241,4 +241,4 @@ export default function Page() { } ``` -**Note:** The [`useAuth`](/docs/next/reference/custom-hooks#useauth) hook fetches the applicable tokens and ensures that the user is authenticated. Therefore, you should check for `isAuthenticated` prior to making authenticated requests, as doing so too early will result in a request without a valid access token. +**Note:** The [`useAuth`](/docs/next/reference/hooks/useAuth) hook fetches the applicable tokens and ensures that the user is authenticated. Therefore, you should check for `isAuthenticated` prior to making authenticated requests, as doing so too early will result in a request without a valid access token. diff --git a/docs/next/guides/fetching-data.mdx b/docs/next/guides/fetching-data.mdx index e5be4e9ed..92f052140 100644 --- a/docs/next/guides/fetching-data.mdx +++ b/docs/next/guides/fetching-data.mdx @@ -104,20 +104,20 @@ To do this you will need to run `gqty generate` again. Running `gqty generate` w ## Providing the GQty Client to Faust.js -Using the boilerplate client code will provide two different GQty clients that you can use depending upon whether you are on the client or server. However, you will still need to provide the client to Faust.js so that it can use it to fetch data. To do this you can use the `HeadlessProvider` component published by Faust.js, and provide it the GQty client you want to use. This is done in your `_app.tsx` file as follows: +Using the boilerplate client code will provide two different GQty clients that you can use depending upon whether you are on the client or server. However, you will still need to provide the client to Faust.js so that it can use it to fetch data. To do this you can use the `FaustProvider` component published by Faust.js, and provide it the GQty client you want to use. This is done in your `_app.tsx` file as follows: ```tsx title=src/pages/_app.tsx {2,9,11} import 'faust.config'; -import { HeadlessProvider } from '@faustjs/next'; +import { FaustProvider } from '@faustjs/next'; import { client } from 'client'; import type { AppProps } from 'next/app'; export default function MyApp({ Component, pageProps }: AppProps) { return ( <> - + - + ); } @@ -127,11 +127,11 @@ This will ensure Faust.js uses the correct client to make requests on your behal ## Using the Client to Make Queries -Assuming you have created a client using the Faust.js `getClient` function, you will be able to take advantage of many of the added features that Faust.js provides, and also the general features provided by GQty. You can read our [hooks for fething data reference](../reference/custom-hooks) for examples on how to use some of the built-in hooks using the Faust.js client, but the client will support any query to your Headless WordPress API. Let's look at a few examples of how to use the client to make queries. +Assuming you have created a client using the Faust.js `getClient` function, you will be able to take advantage of many of the added features that Faust.js provides, and also the general features provided by GQty. You can read our [hooks for fetching data reference](../reference/hooks) for examples on how to use some of the built-in hooks using the Faust.js client, but the client will support any query to your Headless WordPress API. Let's look at a few examples of how to use the client to make queries. ### The useQuery Hook -If you are not able to use one of the [WordPress-specific hooks](../reference/custom-hooks) you can use the `useQuery` hook to make a query to the Headless WordPress API. This hook is useful for making any query supported by your Headless WordPress API. It essentially exposes your entire generated GQL schema to you for you to use what you need. For example, say you have a `Header` component and you want to fetch menu items from your "Primary" menu in WordPress. You could do so as follows: +If you are not able to use one of the [WordPress-specific hooks](../reference/hooks) you can use the `useQuery` hook to make a query to the Headless WordPress API. This hook is useful for making any query supported by your Headless WordPress API. It essentially exposes your entire generated GQL schema to you for you to use what you need. For example, say you have a `Header` component and you want to fetch menu items from your "Primary" menu in WordPress. You could do so as follows: ```tsx title=src/components/Header.tsx {4,12-15,30-36} import React from 'react'; @@ -222,7 +222,8 @@ export function PostForm() { content: content.value, }, }); - }}> + }} + >