cartflows / docs / wiki / Build-System.md

Build-System.md in CartFlows – Funnel Builder & Checkout Plugin for WooCommerce 3.0.1, at docs/wiki/Build-System.md

160 lines 4.9 KB

Raw Download Zip

1	# Build System
2
3	CartFlows uses `@wordpress/scripts` (Webpack) for compiling two React apps, with Grunt for additional minification tasks. Build artifacts are committed to the repository — no CI build step is required for deployment.
4
5	## Two-App Architecture
6
7	Two React apps are compiled independently:
8
9	\| App \| Entry Point \| Output Files \| Used On \|
10	\|-----\|-------------\|-------------\|---------\|
11	\| `editor-app` \| `admin-core/assets/src/EditorApp.js` \| `editor-app.js`, `editor-app.css`, `editor-app.asset.php` \| Flow editor, step editor pages \|
12	\| `settings-app` \| `admin-core/assets/src/SettingsApp.js` \| `settings-app.js`, `settings-app.css`, `settings-app.asset.php` \| Dashboard, analytics, global settings \|
13
14	The setup wizard has its own separate build using `wizard-webpack-config.js`.
15
16	## Build Commands
17
18	```bash
19	# Build both apps for production
20	npm run build
21
22	# Development watch mode (rebuilds on file change)
23	npm run start
24
25	# Build the setup wizard only
26	npm run wizard-build
27
28	# Build all three (main apps + wizard)
29	npm run all-builds
30	```
31
32	## Webpack Configuration
33
34	The main apps use the default `@wordpress/scripts` Webpack configuration. No custom `webpack.config.js` is needed — `wp-scripts` discovers entry points automatically from `package.json` or the default pattern.
35
36	The wizard app uses a custom configuration:
37
38	```
39	wizard-webpack-config.js → wizard/ app build
40	```
41
42	## Asset Pipeline
43
44	```
45	admin-core/assets/src/
46	├── EditorApp.js (React 18 entry)
47	├── SettingsApp.js (React 18 entry)
48	├── common/ (shared components + SCSS)
49	├── fields/ (form field components)
50	├── flow-editor/ (canvas, nodes, edges)
51	├── step-editor/ (step settings panels)
52	├── settings-app/ (dashboard, analytics, flows list)
53	├── utils/ (SettingsProvider, helpers)
54	└── importer/ (template library)
55
56	↓ npm run build
57
58	admin-core/assets/build/
59	├── editor-app.js
60	├── editor-app.css
61	├── editor-app.asset.php (dependency manifest)
62	├── settings-app.js
63	├── settings-app.css
64	└── settings-app.asset.php
65	```
66
67	## Asset Manifest Files
68
69	`@wordpress/scripts` generates a `.asset.php` file alongside each bundle. These PHP files export the bundle's dependencies and version hash, used by `wp_enqueue_script()`:
70
71	```php
72	// Example: editor-app.asset.php
73	return array(
74	'dependencies' => array( 'react', 'react-dom', 'wp-components', ... ),
75	'version' => 'abc123',
76	);
77	```
78
79	## Committed Build Artifacts
80
81	Build artifacts in `admin-core/assets/build/` are tracked in git. This means:
82
83	- Deployment does not require a build step
84	- PRs that change React source must include updated build files
85	- Run `npm run build` before committing any JS/CSS changes
86
87	Important: RTL CSS files (`editor-app-rtl.css`, `settings-app-rtl.css`) were intentionally removed. Do not re-add them.
88
89	## CSS / PostCSS
90
91	Tailwind CSS is processed via PostCSS:
92
93	```
94	src/*/.scss + tailwind.config.js
95	↓ postcss (via wp-scripts)
96	admin-core/assets/build/*.css
97	```
98
99	Global styles are imported in `common/all-config.scss`.
100
101	## JavaScript Linting
102
103	```bash
104	npm run lint-js # Run ESLint (WordPress config)
105	npm run lint-js:fix # Auto-fix ESLint + Prettier violations
106	```
107
108	Configuration: `@wordpress/eslint-plugin` with `wp-prettier` for formatting.
109
110	## CSS Linting
111
112	```bash
113	npm run lint-css # Run Stylelint
114	npm run lint-css:fix # Auto-fix Stylelint violations
115	```
116
117	## Prettier
118
119	```bash
120	npm run pretty # Check formatting
121	npm run pretty:fix # Auto-fix formatting
122	```
123
124	## Internationalisation (i18n)
125
126	```bash
127	npm run i18n # Extract all translatable strings
128	npm run i18n:po # Generate .po files
129	npm run i18n:mo # Compile .mo files
130	npm run i18n:json # Generate .json files for JS translations
131	```
132
133	Language-specific targets exist for: Dutch (nl), French (fr), German (de), Spanish (es), Italian (it), Portuguese (pt), Polish (pl).
134
135	## Grunt
136
137	Grunt is available for additional minification tasks not covered by `wp-scripts`. Gruntfile.js at the root defines minification targets. Grunt is not part of the primary build pipeline.
138
139	## Path Aliases
140
141	`@wordpress/scripts` Webpack config supports path aliases configured in `package.json` or via a custom Webpack config. The editor app uses aliases such as:
142
143	\| Alias \| Resolved Path \|
144	\|-------\|--------------\|
145	\| `@Editor` \| `admin-core/assets/src/flow-editor/` \|
146	\| `@Utils` \| `admin-core/assets/src/utils/` \|
147	\| `@Alert` \| `admin-core/assets/src/common/confirm-popup/` \|
148
149	## Pre-commit Hook
150
151	Running `npm install` copies a git pre-commit hook that runs linting checks before each commit. Do not bypass with `--no-verify` unless explicitly approved.
152
153	## Related Pages
154
155	- [](Frontend-ArchitectureFrontend-Architecture](Frontend-Architecture](Frontend-Architecture)
156	- [](Editor-AppEditor-App](Editor-App](Editor-App)
157	- [](Settings-AppSettings-App](Settings-App](Settings-App)
158	- [](Contributing-GuideContributing-Guide](Contributing-Guide](Contributing-Guide)
159	- [](Deployment-GuideDeployment-Guide](Deployment-Guide](Deployment-Guide)
160