bricolo
Version:
A development tool for running PHP, JS, and Sass in parallel.
181 lines (122 loc) • 5.17 kB
Markdown
# bricolo
```bricolo``` is a streamlined development tool that enhances your PHP projects by automating common tasks like launching a PHP server, live-reloading with browser sync, and automatically compiling Sass and TypeScript. With a single command, you can set up a fully integrated development environment for both front-end and back-end workflows.
### Features
- Launch a PHP server with automatic configuration.
- Live-build and compile Sass and Typescript on file changes.
- Instant browser reloading with hot reloading support.
- Simple setup with one command.
<details open="open">
<summary>Table of Contents</summary>
<ul>
<li><a href="#installation">Installation</a></li>
<li><a href="#configuration">Configuration</a></li>
<li><a href="#usage">Usage</a></li>
<li><a href="#contact">Contact 📧</a></li>
</ul>
</details>
## Installation
To install ```bricolo```, use npm:
```bash
npm install bricolo@latest
```
Ensure that you have the following dependencies installed:
- Node.js (v12 or higher)
- PHP (for the built-in server)
Sass and TypeScript are automatically handled, so you don’t need to worry if they aren’t pre-installed in your project.
## Configuration
```bricolo``` uses two configuration files:
1. A default configuration located in the package's directory (```config.json```)
2. An optional user configuration that you can create at the root of your project (```bricoloconfig.json```), which can override the default settings.
### Default values
Here is the default configuration file ```config.json```
```json
{
"phpServer": {
"port": 8000,
"command": "php -S localhost:{port} -t dist/"
},
"jsBuild": {
"entry": "src/js/app.ts",
"output": "dist/js/bundle.js"
},
"sassBuild": {
"entry": "src/scss/styles.scss",
"output": "dist/css/style.min.css"
},
"watch": {
"directories": [
"src/**/*"
]
},
"server": {
"port": 8080
}
}
```
### Configuration parameters
- **phpServer.port**: The port on which the PHP server will run.
- **phpServer.command**: The command to run the PHP server (support placeholder for the port).
- **jsBuild.entry**: Path to the TypeScript/JavaScript entry file for ```esbuild```.
- **jsBuild.output**: Path where the output JavaScript bundle will be generated.
- **jsBuild.output**: Path where the output JavaScript bundle will be generated.
- **sassBuild.entry**: Path to the Sass entry file.
- **sassBuild.output**: Path where the compiled CSS will be saved.
- **server.port**: The port for the live-reloading server (```browser-sync```).
- **watch.directories**: List of directories or files to watch for changes to trigger browser reload.
### Default structure
After installation, you can run the *initiate* script to create the default project structure at the root of your project. This script sets up a basic folder structure with default TypeScript and Sass files, like described in the default ```config.json``` file.
In order to run this script, please type:
```bash
npx bricolo init
```
You'll be prompted:
```bash
Would like to create the default structure? [no, yes]: (no)
```
If you choose **Y**, the following structure will be created.
```bash
src/
js/
app.ts # Default TypeScript file
scss/
styles.scss # Default Sass file
dist/
css/
js/
index.php
```
**Example Default files**
- app.ts:
```typescript
// Default TypeScript file
console.log("Hello, TypeScript!");
```
- styles.scss
```scss
// Default SASS file
body {
background-color: #f0f0f0;
}
```
If you prefer to skip this step, simply respond N to the prompt, and you can always create the structure manually later. Just make sure your ```bricoloconfig.json``` matches the structure of your files.
## Usage
Once the package is installed and configured, we strongly recommand to add the following script in the ```package.json```:
```bash
{
"scripts": {
"serve": "bricolo serve"
}
}
```
Then just run the command ```npm run serve```. Alternatively, you can directly type ```npx bricolo serve``` in you terminal, without creating a script in you ```package.json```. This will:
- Start a PHP server on the configured port.
- Automatically build and watch your Sass and TypeScript files.
- Refresh the browser in real-time when files are modified.
### Example Workflow
1. Edit your ```src/scss/styles.scss``` or ```src/js/app.ts```
2. Watch the changes live-build and reload in the browser.
3. Enjoy a smoother front-end/back-end development cycle.
## Contact
If you have any question about this package, how to install, to use or to improve, feel free to contact me:
Antoine Bollinger - [LinkedIn](https://www.linkedin.com/in/antoinebollinger/) - [antoine.bollinger@gmail.com](mailto:antoine.bollinger@gmail.com)
You can talk to me in 🇫🇷, 🇧🇷 or 🇬🇧.