VerbalExpressions Deployment and Usage Guide

1. Prerequisites

Runtime Requirements

• Node.js (for server-side usage)
• Modern web browser (for client-side usage)

Development Tools

• npm (Node Package Manager) - comes with Node.js installation
• Git - for cloning the repository
• Babel - for transpiling ES6 code (included in build process)
• ESLint - for code linting (included in development dependencies)

Optional Tools

• Ruby and Bundler - for building documentation (if modifying docs)
• Grunt - for running build tasks (included in dev dependencies)

2. Installation

Option 1: Using npm (Recommended)

npm install verbal-expressions

Option 2: Clone and Install from Source

# Clone the repository
git clone https://github.com/VerbalExpressions/JSVerbalExpressions.git

# Navigate to the project directory
cd JSVerbalExpressions

# Install dependencies
npm install

Option 3: Browser Usage

For browser usage, include the library directly in your HTML:

<script src="https://cdn.jsdelivr.net/npm/verbal-expressions@latest/dist/verbalexpressions.min.js"></script>

Or download the minified version from the dist/ folder after building.

3. Configuration

Environment Variables

No specific environment variables are required for this library.

Configuration Files

No configuration files are needed. The library works out of the box.

API Keys

No API keys are required for this library.

4. Build & Run

Building the Library

# Build the library (creates dist/verbalexpressions.js and dist/verbalexpressions.min.js)
npm run build

Running Tests

# Run tests
npm test

# Run tests with verbose output
npm run test:verbose

Linting

# Check code style
npm run lint

Development Workflow

1. Make changes to VerbalExpressions.js
2. Run npm run build to create updated versions
3. Run npm test to ensure tests pass
4. Run npm run lint to check code style

5. Deployment

For Browser Applications

Since this is a JavaScript library, deployment depends on your application:

• Static hosting (Vercel, Netlify, GitHub Pages) for frontend applications
• Server-side applications (Node.js) deployed to platforms like:
  • Heroku
  • Railway
  • AWS Lambda
  • DigitalOcean App Platform

Including in Your Project

// Node.js/CommonJS
const VerEx = require('verbal-expressions');

// ES6 Modules
import VerEx from 'verbal-expressions';

// Browser (after including the script)
const tester = VerEx().startOfLine().then('http').maybe('s').then('://');

CDN Usage

For quick prototyping or simple projects, use the jsDelivr CDN:

<script src="https://cdn.jsdelivr.net/npm/verbal-expressions@latest/dist/verbalexpressions.min.js"></script>

6. Troubleshooting

Common Issues and Solutions

1. "Cannot find module 'verbal-expressions'"

Solution: Install the package using npm install verbal-expressions or ensure your node_modules directory is properly set up.

2. Build Fails with Babel Errors

Solution: Ensure you have the correct Node.js version installed. The project uses Babel for transpilation, so check that your Node.js version is compatible with the project's Babel configuration.

3. Tests Failing

Solution: Run npm test to see specific test failures. Common issues include:

• Incorrect regular expression patterns
• Changes that break existing functionality
• Ensure you're testing against the built version if using the minified file

4. ESLint Errors

Solution: Run npm run lint to identify code style issues. The project follows Airbnb JavaScript style guide. Fix any reported issues or add exceptions in .eslintrc if necessary.

5. Browser Compatibility Issues

Solution: Use the built and minified versions from the dist/ folder, which are transpiled to be compatible with older browsers. If you need to support very old browsers, consider using a polyfill for RegExp extensions.

6. Documentation Build Issues

Solution: If modifying documentation, ensure Ruby and Bundler are installed, then run:

cd docs/
bundle install
bundle exec jekyll build

7. Performance Issues with Complex Patterns

Solution: While VerbalExpressions makes regex construction easier, complex patterns can impact performance. Test with realistic data sizes and consider simplifying patterns when possible.