woocommerce/plugins/woocommerce-admin/README.md

121 lines
4.4 KiB
Markdown
Raw Normal View History

# WooCommerce Admin
This is a feature plugin for a modern, javascript-driven WooCommerce Admin experience.
## Prerequisites
[WordPress 5.6 or greater](https://wordpress.org/download/) and [WooCommerce 5.7.0 or greater](https://wordpress.org/plugins/woocommerce/) should be installed prior to activating the WooCommerce Admin feature plugin.
For better debugging, it's also recommended you add `define( 'SCRIPT_DEBUG', true );` to your wp-config. This will load the unminified version of all libraries, and specifically the development build of React.
## Development
2019-08-21 19:17:05 +00:00
After cloning the repo, install dependencies:
- `pnpm install` to install JavaScript dependencies.
- `composer install` to gather PHP dependencies.
2019-08-21 19:17:05 +00:00
Now you can build the files using one of these commands:
- `pnpm run build` : Build a production version
- `pnpm run dev` : Build a development version
- `pnpm start` : Build a development version, watch files for changes
- `pnpm run build:release` : Build a WordPress plugin ZIP file (`woocommerce-admin.zip` will be created in the repository root)
- `DRY_RUN=1 pnpm run build:release` : Builds a Wordpress plugin ZIP **without** pushing it to Github and creating a release.
For more helper scripts [see here](./CONTRIBUTING.md#helper-scripts)
For some debugging tools/help [see here](./CONTRIBUTING.md#debugging)
For local development setup using Docker [see here](./docker/wc-admin-wp-env/README.md)
Enable Typescript checking on ./client folder (https://github.com/woocommerce/woocommerce-admin/pull/8372) * Copied .tsconfig into ./client to enable ts checking - Made sub-repos composite typescript packages where necessary * Prevent tsc from transpiling ./client - we use webpack for transpiling so no need for this * Added tsc resolution path for @automattic/explat-client - Seems like there's a type export issue (?) with @automattic/explat-client and @automattic/explat-client-react-helpers - adding the node_modules/@automattic/explat-client path in tsconfig seems to help TS resolve this using the source .ts files - found answer here: https://github.com/microsoft/TypeScript/issues/42873 - should figure out what's actually wrong with the type exports and fix that there instead * Removed mandatory checking from webpack - removed this for now as it will block all development until all type inconsistencies are fixed - for now, run the optional ts:check task either in console or vscode for highlighting type errors * Added vscode tasks for typescript checking * Patch @automattic/explat-client-react-helpers - this changes the installed code in node_modules (post-installation) for @automattic/explat-client-react-helpers so that it exports the necessary type interfaces required by us - attempted unsuccessfully to override type exports using declare module - not too sure how to fix this internally by other means - have to investigate what fixes to propose to @automattic/explat-client-react-helpers team * changed tests in ./client to use ts-jest instead of babel-jest - rewrote jest config to use ts-jest instead of babel-jest - set ts errors to warnings instead so that tests don't fail on type errors - created new tsconfig for ./packages/js-tests so that build and ts-check are separate, as js-tests need to be built for commonjs
2022-03-01 04:19:07 +00:00
### Typescript
The `npm run ts:check` command will check your TypeScript files for errors, and has been added to `.vscode/tasks.json`.
Running this task in vscode will highlight the errors in your editor file navigator.
If you allow the `npm run ts:check:watch` command to run automatically as configured, it will run in the background and pick up any errors as you save the files.
Note: Even if you don't run this task, the IDE uses its language server to pick up type errors in files that are open. This is only necessary for picking up errors
across the entire repository even when they haven't been opened in the IDE.
### Testing
#### End-to-end tests
Tests live in `./tests/e2e`. An existing build is required prior running, please refer to the section above for steps. E2E tests use the `@woocommerce/e2e-environment` package which hosts a Docker container for testing, by default the container can be accessed at `http://localhost:8084`
All the commands from `@woocommerce/e2e-environment` can be run through `pnpm exec`.
```
# Set up the e2e environment
pnpm i
pnpm exec wc-e2e docker:up
```
Run tests using:
```
pnpm exec wc-e2e test:e2e-dev
```
or in headless mode:
```
pnpm exec wc-e2e test:e2e
```
Run a single test by adding the path to the file name:
```
pnpm exec wc-e2e test:e2e-dev tests/e2e/specs/activate-and-setup/complete-onboarding-wizard.test.ts
```
### Documentation
There is documentation in 2 forms available in the repo. A static set of documentation supported by docsify and also a Storybook containing component documentation for `@woocommerce/components`.
To view the docsify docs locally you can do:
```
pnpm install
cd docs
pnpm exec docsify serve
```
When deployed the docsify docs also host an embedded version of the storybook docs. To generate that and test it locally in docsify you'll need to run:
```
pnpm install
pnpm run docs
cd docs
pnpm exec docsify serve
```
Then navigate to `Components` from the left hand menu in the docs.
If you would like to view the storybook docs hosted standalone, then you can run:
```
pnpm install
pnpm run storybook
```
If you would like to view the storybook docs in right-to-left styling, you can run this instead:
```
pnpm install
pnpm run storybook-rtl
```
## Common Issues
If you're encountering any issue setting things up, chances are we have been there too. Please have a look at our [wiki](https://github.com/woocommerce/woocommerce-admin/wiki/Common-Issues) for a list of common problems.
2018-10-17 20:49:06 +00:00
## Privacy
If you have enabled WooCommerce usage tracking ( option `woocommerce_allow_tracking` ) then, in addition to the tracking described in https://woocommerce.com/usage-tracking/, this plugin also sends information about the actions that site administrators perform to Automattic - see https://automattic.com/privacy/#information-we-collect-automatically for more information.
## Contributing
There are many ways to contribute reporting bugs, adding translations, feature suggestions and fixing bugs. For full details, please see [CONTRIBUTING.md](./CONTRIBUTING.md)