Riot.js Deployment and Usage Guide

Prerequisites

• Node.js (version 12.0.0 or higher)
• npm (version 6.0.0 or higher)
• Modern web browser (Chrome, Firefox, Safari, or Edge)

Installation

1. Clone the Repository

git clone git@github.com:riot/riot.git
cd riot

2. Set Up Your Git Branch

git checkout -b feature/my-awesome-patch

3. Install Dependencies

npm i

4. Build and Test

# To build and test riot
make riot

# To build without testing
make raw

Configuration

Environment Variables

For running tests with Sauce Labs in CI:

export SAUCE_USERNAME=your_sauce_username
export SAUCE_ACCESS_KEY=your_sauce_access_key

Development Configuration

The project uses a Makefile for build and test commands. No additional configuration files are required for local development.

Build & Run

Local Development

1. Build the project:

   make riot
   

2. Run tests:

   npm test
   

3. Watch mode (if available):

   npm run watch
   

Production Build

1. Create a production build:

   make raw
   

2. The compiled library will be available in the project root as riot.min.js

Deployment

CDN Hosting

Riot.js is available on multiple CDNs:

• unpkg: https://unpkg.com/riot/riot.js
• jsDelivr: https://www.jsdelivr.com/projects/riot
• cdnjs: https://cdnjs.com/libraries/riot

Package Managers

Install Riot.js via npm:

npm install riot

Framework Integration

Riot.js can be integrated with various build tools:

• Webpack: Use riot/webpack-loader
• Rollup: Use riot/rollup-plugin-riot
• Parcel: Use riot/parcel-plugin-riot
• Browserify: Use riot/riotify

Troubleshooting

Common Issues

1. Build Failures

Issue: make riot fails with compilation errors

Solution:

• Ensure Node.js version is 12.0.0 or higher
• Run npm ci to clean and reinstall dependencies
• Check that all git submodules are initialized: git submodule update --init

2. Test Failures

Issue: Tests fail in CI but pass locally

Solution:

• Verify Sauce Labs credentials are set in environment variables
• Check that the Sauce Connect proxy is running
• Ensure the correct region is specified in wdio.conf.js

3. Component Mounting Issues

Issue: Custom components don't render

Solution:

• Verify the component syntax follows Riot.js conventions
• Check that the component is properly mounted: riot.mount('component-name')
• Ensure the component script exports a default object with lifecycle methods

4. CSS Injection Problems

Issue: Styles are not being applied to components

Solution:

• Verify the CSS manager is properly injecting styles
• Check that the style node selector style[riot] exists in the DOM
• Ensure no other CSS is overriding the component styles

Getting Help

• Documentation: https://riot.js.org
• Discord Community: Join Discord
• GitHub Issues: Report issues

Contributing

If you encounter issues while contributing:

1. Check the pull request template
2. Ensure your patch is against the main branch
3. Be patient with the review process

For detailed contribution guidelines, see the README.