Local Development Setup
اقتراح تعديلCreate a reproducible local checkout, run PHP and frontend development servers, and keep generated files out of source control.
On this pageJump to a section
Understand the code layout, install locked dependencies, and make a change without editing only a generated public copy.
Tools and source access
Use Git, PHP 8.3+, Composer 2, a MySQL/MariaDB service, and Node/npm compatible with the frontend lockfile. The deployed Vite dependencies require Node ^20.19.0 or >=22.12.0. Make sure GitLab access is configured; an authentication error is not an application installation failure.
git clone https://gitlab.com/prestaworld12/wentoshopper.git wentocart
cd wentocart
git switch -c docs-first-local-change
php -v
composer --version
node --version
npm --versionInstall a fresh local store
cp .env.example .env
composer install
php artisan key:generate
npm ci
npm run build
php artisan wento:theme-publish
php artisan wento:doctor
php artisan wento:installUse a new empty local database and the interactive installer. Keep local credentials in .env. The prepared release ZIP skips the source build steps because assets are already included; a Git checkout does not.
Do not run composer update as a routine setup command. composer install uses the release lockfile. Likewise, npm ci is suitable when package.json and package-lock.json are in sync; fix a deliberate dependency change in a reviewed branch rather than deleting the lock to hide a failure.
Run the app while developing
php artisan serve --host=127.0.0.1 --port=8000Leave that process running. In a second terminal in the same project:
npm run devOpen the Laravel URL for the storefront and /admin/login for admin. The Vite server serves development assets; it is not the main application URL. When stopping development, build production assets before testing without Vite. Remove an obsolete public/hot file only after confirming the development server is stopped and the production manifest exists.
Know where to edit
| Source path | Responsibility |
|---|---|
| app/Domain | Commerce domain logic and services |
| app/Http and routes | Request handling and route registration |
| resources/js/admin | Inertia/React admin interface |
| storefront/src | Bundled storefront React source |
| themes/classic | Tracked bundled theme assets |
| extensions/{vendor}/{name} | Extension source and manifest |
| public/build and public/themes | Generated or published files; do not treat these as the only source of a change |
Read AGENTS.md and the relevant domain notes in the checkout before changing architecture. Follow the existing shared admin UI and translation helpers. Prefer extensions and child themes for store customizations.
Verify your work and collaborate
- Reproduce the issue on your local store using a small, known dataset.
- Change the tracked source file and run relevant checks for that area. Use php artisan test when appropriate; review available test configuration first.
- Run npm run build for frontend changes and php artisan wento:theme-publish when bundled theme assets changed.
- Review git diff and git status. Exclude .env, dependencies, local uploads, logs, and generated build folders unless the repository explicitly tracks them.
- Commit a focused change and open a merge request against the intended branch. Re-test after incorporating upstream changes.
After pulling a release or another developer’s changes, review migration/upgrade instructions before touching the database. A successful git pull alone does not refresh dependencies, compiled assets, or a running worker.
When the local setup fails
Compare the PHP binary shown by php -v with your web PHP. Confirm the database is running and your URL/port matches .env. For a blank admin, check the browser’s failed asset URL, the Vite process or production manifest, and the PHP log. Use Installation Errors instead of reinstalling an existing database.
Continue learning
Installing WentoCart · Build an Extension · Customize the Storefront