✨ (build): Introduce nuevas funciones de build
Añade `compile_scss()`, `copy_dir()`, `copy_file()`, `copy_file_replacing()` y `minify_js()` para preparar activos en `build.rs`. Adopta el patrón `assets/ -> static/`: los archivos estáticos se mueven a `assets/` y `static/` se añade a `.gitignore`. Los `build.rs` de *pagetop* y *pagetop-htmx* se actualizan con el nuevo patrón. La documentación del módulo se reescribe para reflejar los nuevos cambios.
This commit is contained in:
parent
6376e3e88c
commit
f27790c3a2
26 changed files with 468 additions and 236 deletions
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
<h1>PageTop Build</h1>
|
||||
|
||||
<p>Prepara un conjunto de archivos estáticos o archivos SCSS compilados para ser incluidos en el binario de un proyecto <strong>PageTop</strong>.</p>
|
||||
<p>Genera o prepara archivos estáticos para servirlos o incluirlos en un proyecto <strong>PageTop</strong>.</p>
|
||||
|
||||
[](https://docs.rs/pagetop-build)
|
||||
[](https://crates.io/crates/pagetop-build)
|
||||
|
|
@ -19,81 +19,77 @@ configurables, basadas en HTML, CSS y JavaScript.
|
|||
|
||||
## Guía rápida
|
||||
|
||||
Añadir en el archivo `Cargo.toml` del proyecto:
|
||||
La convención recomendada para extensiones, temas o aplicaciones basadas en **PageTop** es separar
|
||||
los archivos fuente de los generados siguiendo el patrón `assets/` -> `static/`:
|
||||
|
||||
```toml
|
||||
[build-dependencies]
|
||||
pagetop-build = { ... }
|
||||
```
|
||||
- **`assets/`** - archivos versionados en el repositorio, por ejemplo archivos SCSS, JavaScript de
|
||||
terceros, fuentes, etc. Todo lo que hay aquí se sube al repositorio y será la fuente para generar
|
||||
el directorio final `static/`.
|
||||
- **`static/`** - archivos generados en tiempo de compilación a partir de `assets/`. Se añade a
|
||||
`.gitignore` y nunca se sube al repositorio.
|
||||
- **`build.rs`** - orquesta la transformación: genera `static/` desde `assets/` para servirlos o
|
||||
incluirlos en el proyecto.
|
||||
|
||||
Y crear un archivo `build.rs` a la altura de `Cargo.toml` para indicar cómo se van a incluir los
|
||||
archivos estáticos o cómo se van a compilar los archivos SCSS para el proyecto. Casos de uso:
|
||||
Durante el desarrollo, `static/` existe en disco y los archivos se sirven desde ahí. En producción,
|
||||
el directorio no existe y los recursos salen del binario. La macro
|
||||
[`serve_static_files!`](https://docs.rs/pagetop/latest/pagetop/macro.serve_static_files.html)
|
||||
gestiona esta dualidad de forma transparente.
|
||||
|
||||
### Incluir archivos estáticos desde un directorio
|
||||
### Funciones de transformación
|
||||
|
||||
Hay que preparar una carpeta en el proyecto con todos los archivos que se quieren incluir, por
|
||||
ejemplo `static`, y añadir el siguiente código en `build.rs` para crear el conjunto de recursos:
|
||||
Estas funciones se usan en el `build.rs` de cada proyecto para generar `static/` a partir de
|
||||
`assets/`. Todas crean el directorio padre del destino si no existe y devuelven `io::Result<()>`
|
||||
para poder propagarse con `?` en caso de error.
|
||||
|
||||
- `compile_scss()` - compila un archivo SCSS a CSS minificado.
|
||||
- `copy_dir()` - copia recursivamente un directorio completo. Útil para copiar todos los archivos de
|
||||
`assets/` o de un subdirectorio a `static/` sin transformación.
|
||||
- `copy_file()` - copia un archivo al destino.
|
||||
- `copy_file_replacing()` - copia un archivo aplicando una lista de sustituciones de texto en su
|
||||
contenido; útil para actualizar referencias internas (p.ej. `sourceMappingURL`) al renombrar
|
||||
archivos.
|
||||
- `minify_js()` - minifica un archivo JavaScript.
|
||||
|
||||
### Incluir los archivos estáticos en el proyecto
|
||||
|
||||
Una vez generado `static/`, usaremos `StaticFilesBundle` para incluir su contenido en el binario. Se
|
||||
pueden crear tantos paquetes de recursos como sea necesario, siempre que tengan nombres distintos:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop_build::StaticFilesBundle;
|
||||
|
||||
fn main() -> std::io::Result<()> {
|
||||
StaticFilesBundle::from_dir("./static", None)
|
||||
.with_name("guides")
|
||||
StaticFilesBundle::from_dir("./static/css", None)
|
||||
.with_name("app_css")
|
||||
.build()?;
|
||||
StaticFilesBundle::from_dir("./static/fonts", None)
|
||||
.with_name("app_fonts")
|
||||
.build()
|
||||
}
|
||||
```
|
||||
|
||||
Si es necesario, se puede añadir un filtro para seleccionar archivos específicos de la carpeta, por
|
||||
ejemplo:
|
||||
Si es necesario excluir algunos archivos del paquete de recursos (p. ej. los archivos `.map` que no
|
||||
son necesarios en producción), se puede pasar una función de filtro:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop_build::StaticFilesBundle;
|
||||
use std::path::Path;
|
||||
|
||||
fn main() -> std::io::Result<()> {
|
||||
fn only_pdf_files(path: &Path) -> bool {
|
||||
// Selecciona únicamente los archivos con extensión `.pdf`.
|
||||
path.extension().map_or(false, |ext| ext == "pdf")
|
||||
}
|
||||
|
||||
StaticFilesBundle::from_dir("./static", Some(only_pdf_files))
|
||||
.with_name("guides")
|
||||
StaticFilesBundle::from_dir("./static/js", Some(only_js))
|
||||
.with_name("app_js")
|
||||
.build()
|
||||
}
|
||||
|
||||
fn only_js(path: &Path) -> bool {
|
||||
path.extension().map_or(false, |ext| ext == "js")
|
||||
}
|
||||
```
|
||||
|
||||
### Compilar archivos SCSS a CSS
|
||||
|
||||
Se puede compilar un archivo SCSS, que podría importar otros a su vez, para preparar un recurso con
|
||||
el archivo CSS minificado obtenido. Por ejemplo:
|
||||
|
||||
```rust,no_run
|
||||
use pagetop_build::StaticFilesBundle;
|
||||
|
||||
fn main() -> std::io::Result<()> {
|
||||
StaticFilesBundle::from_scss("./styles/main.scss", "styles.min.css")
|
||||
.with_name("main_styles")
|
||||
.build()
|
||||
}
|
||||
```
|
||||
|
||||
Este código compila el archivo `main.scss` de la carpeta `static` del proyecto, y prepara un recurso
|
||||
llamado `main_styles` que contiene el archivo `styles.min.css` obtenido.
|
||||
|
||||
## Archivos generados
|
||||
|
||||
Cada conjunto de recursos [`StaticFilesBundle`] genera un archivo en el directorio estándar
|
||||
[OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts)
|
||||
donde se incluye el código necesario para compilar el proyecto. Por ejemplo, para
|
||||
`with_name("guides")` se genera un archivo llamado `guides.rs`.
|
||||
|
||||
No hay ningún problema en generar más de un conjunto de recursos para cada proyecto siempre que se
|
||||
usen nombres diferentes.
|
||||
|
||||
Normalmente no habrá que acceder a estos módulos; sólo declarar el nombre del conjunto de recursos
|
||||
en [`serve_static_files!`](https://docs.rs/pagetop/latest/pagetop/macro.serve_static_files.html)
|
||||
para configurar un servicio web que sirva los archivos desde la ruta indicada. Por ejemplo:
|
||||
Cada paquete de recursos genera un archivo `.rs` en
|
||||
[OUT_DIR](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts).
|
||||
No es necesario acceder a él directamente: el nombre asignado con `.with_name()` se usa como
|
||||
identificador en `serve_static_files!` para configurar la ruta del servicio:
|
||||
|
||||
```rust,ignore
|
||||
use pagetop::prelude::*;
|
||||
|
|
@ -101,14 +97,47 @@ use pagetop::prelude::*;
|
|||
pub struct MyExtension;
|
||||
|
||||
impl Extension for MyExtension {
|
||||
/// Registra los recursos de `guides` en el router bajo `/ruta/a/guides`.
|
||||
fn configure_router(&self, mut router: Router) -> Router {
|
||||
serve_static_files!(router, [guides] => "/ruta/a/guides");
|
||||
serve_static_files!(router, ["./static/css", app_css] => "/public/css");
|
||||
router
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Ejemplo completo
|
||||
|
||||
```rust,no_run
|
||||
use pagetop_build::StaticFilesBundle;
|
||||
use pagetop_build::{compile_scss, copy_file, copy_file_replacing, minify_js};
|
||||
use std::path::Path;
|
||||
|
||||
fn main() -> std::io::Result<()> {
|
||||
// Regenera `static/` desde cero sólo si hay cambios en `assets/`.
|
||||
println!("cargo:rerun-if-changed=assets");
|
||||
let _ = std::fs::remove_dir_all("static");
|
||||
|
||||
// Genera `static/` a partir de `assets/`.
|
||||
compile_scss("assets/main.scss", "static/css/main.min.css")?;
|
||||
copy_file("assets/fonts/icon.woff2", "static/fonts/icon.woff2")?;
|
||||
copy_file_replacing(
|
||||
"assets/lib.min.js",
|
||||
"static/js/app.min.js",
|
||||
&[("lib.min.js.map", "app.min.js.map")],
|
||||
)?;
|
||||
minify_js("assets/shell.js", "static/js/shell.min.js")?;
|
||||
|
||||
// Prepara los paquetes de recursos para incluir en el proyecto.
|
||||
StaticFilesBundle::from_dir("./static/css", None).with_name("app_css").build()?;
|
||||
StaticFilesBundle::from_dir("./static/js", Some(only_js)).with_name("app_js").build()?;
|
||||
StaticFilesBundle::from_dir("./static/fonts", None).with_name("app_fonts").build()
|
||||
}
|
||||
|
||||
// Los `.map` no se incluyen, se servirán desde disco durante el desarrollo.
|
||||
fn only_js(path: &Path) -> bool {
|
||||
path.extension().map_or(false, |ext| ext == "js")
|
||||
}
|
||||
```
|
||||
|
||||
## Advertencia
|
||||
|
||||
**PageTop** es un proyecto personal para aprender [Rust](https://www.rust-lang.org/es) y conocer su
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue