Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/apostrophecms/vite
Vite build flow for Apostrophe CMS projects
https://github.com/apostrophecms/vite
Last synced: about 2 months ago
JSON representation
Vite build flow for Apostrophe CMS projects
- Host: GitHub
- URL: https://github.com/apostrophecms/vite
- Owner: apostrophecms
- License: mit
- Created: 2024-10-08T08:44:08.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2024-11-04T15:59:21.000Z (2 months ago)
- Last Synced: 2024-11-04T16:45:43.709Z (2 months ago)
- Language: JavaScript
- Size: 20.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
Apostrophe Vite Bundling And HMR
This extension provides Vite integration for ApostropheCMS projects, enabling module bundling and hot module replacement (HMR) during development.
## Installation
To install the module, use the command line to run this command in an Apostrophe project's root directory:
```
npm install @apostrophecms/vite
```
## Usage
Add the module in the `app.js` file:
```javascript
require('apostrophe')({
shortName: 'my-project',
modules: {
'@apostrophecms/vite': {},
}
});
```
## Configuration
## Hot Module Replacement Configuration
By default, HMR is enabled for your project's public UI code. All configuration is handled through ApostropheCMS's core asset module options, simplifying setup and maintenance.
### Enable Admin UI HMR
For development work on the ApostropheCMS admin interface, you can switch HMR to target the admin UI instead of public-facing components:
```javascript
require('apostrophe')({
shortName: 'my-project',
modules: {
'@apostrophecms/vite': {},
'@apostrophecms/asset': {
options: {
hmr: 'apos', // 'public' targets the project UI (default)
},
},
}
});
```
### Disable HMR
You can disable hot module replacement when it is not needed or desired, while still using Vite for builds:
```javascript
require('apostrophe')({
shortName: 'my-project',
modules: {
'@apostrophecms/vite': {},
'@apostrophecms/asset': {
options: {
hmr: false,
},
},
}
});
```
## Change the underlying Websocket server port
During development, the hot module reload (HMR) server uses WebSocket and runs on the same port as your ApostropheCMS instance. For advanced configurations, you can run the development server as a standalone HTTP server on a different port by setting the `hmrPort` option. This can be useful when you need to avoid port conflicts or work with specific network configurations:
```javascript
require('apostrophe')({
shortName: 'my-project',
modules: {
'@apostrophecms/vite': {},
'@apostrophecms/asset': {
options: {
hmrPort: 3001,
},
},
}
});
```
## Enable Source Maps in Production
You can enable source maps in production to help debug minified code and view original source files in the browser DevTools. While this slightly increases the initial download size, it's valuable for debugging production issues.
```javascript
require('apostrophe')({
shortName: 'my-project',
modules: {
'@apostrophecms/vite': {},
'@apostrophecms/asset': {
options: {
productionSourceMaps: true,
},
},
}
});
```
## Inject code only when HMR is enabled
If you want to inject some code in your site only when in development mode and HMR is enabled, you can use the Apostrophe nunjucks components.
```njk
{# module-name/views/myComponent.html #}
```
```js
// module-name/index.js
module.exports = {
components(self) {
return {
myComponent(req, data) {
return {};
}
};
},
init(self) {
self.apos.template.prepend({
where: 'head',
when: 'hmr',
bundler: 'vite',
component: 'module-name:myComponent'
});
}
};
```
The when option controls when your component appears:
```javascript
when: 'hmr' // Only visible when HMR is active
when: 'dev' // Visible in any development mode
when: 'prod' // Only visible in production
```
The bundler option allows you to specify which bundler must be active for the component to appear:
```javascript
bundler: 'vite' // Only visible when using Vite
bundler: 'webpack' // Only visible when using webpack
```
You can combine these options to precisely control when your component appears. For example, to show a component only when using Vite with HMR active, you would use both `when: 'hmr'` and `bundler: 'vite'`.
## Extending the Vite Configuration
You can customize the Vite configuration for your ApostropheCMS project in two ways:
### 1. Via Any Module `build.vite` Property
Use this approach to configure Vite settings within individual ApostropheCMS modules:
```javascript
// modules/my-module/index.js
module.exports = {
build: {
vite: {
myViteConfig: {
// Standard Vite configuration
define: {
__MY_ENV__: '1',
},
}
},
},
};
```
### 2. Via Project Configuration File
For project-wide Vite configuration, create one of these files in your project root:
- `apos.vite.config.js` (for ESM projects)
- `apos.vite.config.mjs` (for CommonJS projects)
This method supports the full Vite configuration API and applies to your project's UI build. You can import Vite's configuration utilities directly from the ApostropheCMS Vite module:
```javascript
// apos.vite.config.js
import { defineConfig } from '@apostrophecms/vite/vite';
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [ vue() ]
});
```
The configuration format follows the standard [Vite configuration options](https://vitejs.dev/config/). Common use cases include adding plugins, defining environment variables, and customizing build settings.
> Note: All Vite configurations are merged sequentially - first across modules (following module registration order, with later modules taking precedence), and finally with the project configuration file, which takes ultimate precedence.
## Limitations and Known Issues
### Hot Module Replacement
- HMR only monitors existing `anyModule/ui` directories. If you add a new `ui` directory to a module, restart the server to enable HMR for that module. With default ApostropheCMS starter kits using `nodemon`, simply type `rs` in the terminal and press Enter.
### Public Assets
- Changes to `ui/public` directories don't trigger HMR or page reloads as they require a process restart
- Workaround: Add `ui/public/` folders to your `nodemon` watch list in either `nodemon.json` or `package.json`
- Future support for this feature will depend on user needs
### Vite Alias Resolution
- When setting custom `resolve.alias` in Vite configuration, paths must resolve to the appropriate `apos-build/...` source code rather than the original source
- Future enhancement planned: We will provide templating (e.g., `{srcRoot}`) or function arguments (e.g., `aposRoot`) to simplify correct path resolution
## Code Migration Guidelines
### Import Paths
- Remove all `~` prefixes from CSS/Sass imports
```css
/* Instead of: @import "~normalize.css" */
@import "normalize.css"
```
### ApostropheCMS Module Imports
- **Recommended**: Use the `Modules/module-name/components/...` alias instead of direct paths like `apostrophe/modules/module-name/ui/apos/components/...`
- This alias is available only for `apos` source code; project code can define its own aliases
### Module System
- Use only ESM syntax in UI source code:
- ✅ `import abc from 'xxx'` or `const abc = await import('xxx')`
- ✅ `export default ...` or `export something`
- ❌ No CommonJS: `require()`, `module.exports`, `exports.xxx`