Skip to main content
Welcome to the Aikeedo Local Development Guide! This guide will help you set up a local environment for Aikeedo development, assuming you’ve already installed Aikeedo on your machine.
If you haven’t installed Aikeedo locally yet, please refer to our Local Installation Guide first.

​
Prerequisites

Before we dive in, make sure you have the following tools installed on your machine:
  • PHP 8.2 or higher
  • MySQL 8.0 or higher
  • Node.js 18.x or higher
  • npm 9.x or higher
These are the minimum required versions. We recommend using the latest LTS (Long Term Support) versions of Node.js and npm for the best performance and security.
To check if you have these installed and their versions, run the following commands in your terminal: 
php -v
mysql --version
node -v
npm -v
If you need to install or update any of these tools:
We recommend using a version manager like nvm for Node.js, which allows you to easily switch between different Node.js versions.
For more detailed requirements and recommendations, see our Server Requirements page.

​
Step 1: Configure Environment Settings

Let’s set up your environment for local development.
  1. In the Aikeedo root directory, locate the .env file.
  2. Open .env in your favorite text editor and update the following settings: 
    ENVIRONMENT=dev
DEBUG=1
HMR=1
CACHE=0
  3. Save the .env file.
These settings enable development mode, turn on debugging, activate Hot Module Replacement (HMR) for frontend development, and disable caching. This configuration helps you catch errors quickly and see your changes in real-time.

​
Step 2: Set Up Frontend Development

Aikeedo comes pre-built with all necessary frontend assets. However, for local development, you’ll need to start the Vite development server:
  1. Open a terminal in the Aikeedo root directory.
  2. Start the Vite development server: 
    npm run dev
You should see output similar to this: 
  VITE v4.x.x  ready in 123 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help
Keep this terminal window open. It will display compilation errors and automatically update your browser when you make changes to frontend files.
Since Aikeedo is pre-built, you typically don’t need to run npm install or composer install. The necessary dependencies are already included in the package.

​
Understanding the Asset Structure

Aikeedo organizes its assets into two main directories:
  1. /resources/assets: For files that need processing (e.g., JavaScript, SCSS).
    • Example: /resources/assets/js/app/index.js is the main JavaScript entry point.
    • Example: /resources/assets/css/index.scss contains the main styles.
  2. /resources/static: For files that should be copied as-is (e.g., images, fonts).
    • Example: /resources/static/images/logo.png will be copied to /public/images/logo.png.
When adding new assets:
  • Put files that need compilation (JS, CSS) in /resources/assets.
  • Place static files (images, fonts) in /resources/static.
Vite will handle the rest during development and build processes!

​
Step 3: Start the Backend Server

Now, let’s get the PHP server running:
  1. Open a new terminal window (keep the npm process running in the previous one).
  2. Navigate to the Aikeedo root directory.
  3. Start the PHP server: 
    php -S 0.0.0.0:8000 -t public
You should see output like this: 
PHP 8.2.x Development Server (http://0.0.0.0:8000) started

​
Step 4: Access Your Local Aikeedo Instance

Time to see your work in action!
  1. Open your web browser.
  2. Navigate to http://localhost:8000.
You should now see the Aikeedo landing page. Congratulations! 🎉
If you don’t see the page or encounter errors:
  • Ensure both the Vite (npm) and PHP servers are running without errors.
  • Check that your .env file is correctly configured.
  • Verify that your database settings are correct and the database is accessible.

​
Development Workflow

Now that everything is set up, here’s your typical development workflow:
  1. Make changes to PHP files for backend modifications.
    • Example: Edit /src/Presentation/RequestHandlers/IndexRequestHandler.php to modify the home page logic.
  2. Edit files in /resources/views for frontend changes.
    • Example: Modify /resources/views/templates/app/dashboard.twig to update the dashboard layout.
  3. Add or modify static assets in /resources/static.
    • Example: Add a new image at /resources/static/images/new-feature.jpg.
  4. Your browser will automatically reload for frontend changes thanks to HMR.
  5. Refresh your browser to see backend changes take effect.
Remember, this setup is for the core Aikeedo development. For theme-specific work, check out our Theme Development Guide.

​
Building for Production

When you’re ready to build your assets for production:
  1. Open a terminal in the Aikeedo root directory.
  2. Run the build command: 
    npm run build
This process will:
  • Create a public/assets directory with optimized files.
  • Copy static files from /resources/static to /public.
  • Update the asset manifest in /public/.vite.
Avoid adding built files to your Git repository. Instead, include the build process in your deployment workflow.

​
Troubleshooting

If you run into issues:
  • PHP errors: Check the PHP server console and your application’s error log file (typically found in the logs directory).
  • Frontend build errors: Look at the npm/Vite console output.
  • Database issues: Verify your .env settings and MySQL connection.
  • Missing assets: Ensure files are in the correct /resources subdirectory.
For more help, visit our Troubleshooting Guide.

​
Next Steps

Now that you’re all set up, why not explore: Happy coding, and welcome to the world of Aikeedo development! 🚀