Skip to content

QUICKSTART.md

Latest commit

 

History

History
292 lines (225 loc) · 7.68 KB

QUICKSTART.md

File metadata and controls

292 lines (225 loc) · 7.68 KB

Quick Start Guide

Get up and running with WebDevToys Encoders/Decoders tools in minutes. This guide will help you install, run, and start using the developer utilities immediately.

🚀 Quick Start (3 Steps)

Step 1: Installation

# Clone the repository
git clone https://github.com/your-username/webdevtoys.git
cd webdevtoys/specs/003-encoders-decoders-tools

# Install dependencies
npm install

Step 2: Start Development Server

# Start the development server
npm run dev

The application will open automatically at:

Step 3: Start Using Tools

Navigate to any tool using the sidebar or direct URLs:

🛠️ Tool Usage Examples

Base64 Text Encoder

Quick Example:

  1. Go to http://localhost:3000/base64-text-encoder
  2. Type "Hello World" in the input textarea
  3. See "SGVsbG8gV29ybGQ=" appear automatically in the output
  4. Click "Copy Result" to copy to clipboard

Sample Data to Try:

Input:  WebDevToys is awesome! 🚀
Output: V2ViRGV2VG95cyBpcyBhd2Vzb21lISA8ajgyYV8+

QR Code Generator

Quick Example:

  1. Go to http://localhost:3000/qr-code-generator
  2. Enter "https://webdevtoys.dev" in the text field
  3. Select "Medium" error correction
  4. Download the QR code as PNG

Sample Data to Try:

URL: https://github.com/your-repo
WiFi: WIFI:T:WPA;S:MyNetwork;P:MyPassword;;
Contact: BEGIN:VCARD
FN:John Doe
TEL:+1234567890
END:VCARD

URL Encoder/Decoder

Quick Example:

  1. Go to http://localhost:3000/url-encoder
  2. Enter "https://example.com/search?q=hello world&lang=en"
  3. See encoded: "https://example.com/search?q=hello%20world&lang=en"
  4. Switch to decode mode to reverse the process

Sample Data to Try:

Complex URL: https://api.example.com/v1/data?query=hello world&filter[date]=2024-01-01&sort=name%20desc

Base64 Image Encoder

Quick Example:

  1. Go to http://localhost:3000/base64-image-encoder
  2. Drag and drop an image file (or click to select)
  3. Copy the Base64 data URI for use in HTML/CSS
  4. Preview the encoded image

Supported Formats: PNG, JPEG, GIF, WebP, SVG

JWT Token Encoder

Quick Example:

  1. Go to http://localhost:3000/jwt-token-encoder
  2. Enter payload data: {"userId": 123, "role": "admin"}
  3. Set secret key: "your-secret-key"
  4. Generate JWT token
  5. Decode to verify structure

Sample JWT to Decode:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTML Entity Encoder

Quick Example:

  1. Go to http://localhost:3000/html-entity-encoder
  2. Enter: <div class="container">Hello & "World"</div>
  3. See encoded: &lt;div class=&quot;container&quot;&gt;Hello &amp; &quot;World&quot;&lt;/div&gt;
  4. Switch to decode mode to reverse

Sample Data to Try:

HTML: <script>alert('XSS test');</script>
Symbols: © ™ ® € £ ¥ § ¶ † … — "" '' •
Math: ∑ ∏ ∫ ∆ ∇ ∂ √ ∞ ≠ ≤ ≥ ± × ÷

GZip Compression

Quick Example:

  1. Go to http://localhost:3000/gzip-compression
  2. Enter text to compress or select decompress mode
  3. Choose compression level (6 is default)
  4. Select output format (Base64 recommended)
  5. View compression statistics

Sample Data to Try:

Lorem ipsum text for compression testing...
JSON data: {"users":[{"id":1,"name":"John"},{"id":2,"name":"Jane"}]}

Certificate Decoder

Quick Example:

  1. Go to http://localhost:3000/certificate-decoder
  2. Paste PEM certificate (starts with -----BEGIN CERTIFICATE-----)
  3. View parsed certificate information
  4. Check validity dates and issuer details

Sample Certificate Snippet:

-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAJC1HiIAZAiIMA0GCSqGSIb3DQEBBQUAMEUxCzAJBgNV
BAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVQQKDBhJbnRlcm5ldCBX
aWRnaXRzIFB0eSBMdGQwHhcNMTIwOTEyMTUwOTE4WhcNMTUwOTEyMTUwOTE4WjBF
MQswCQYDVQQGEwJBVTETMBEGA1UECAwKU29tZS1TdGF0ZTEhMB8GA1UECgwYSW50
ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB
CgKCAQEAwxKsPqyWQNzwBzLBYJ6EFjND2tCKWXZx9tGdGmbPTXRCGkTzOOkU6DEk
-----END CERTIFICATE-----

🧪 Testing Your Installation

Verify everything works with these quick tests:

Test 1: Basic Functionality

# Run unit tests
npm test

# Check for any errors
npm run lint

Test 2: Browser Testing

  1. Open http://localhost:3000 in your browser
  2. Verify the page loads without errors
  3. Try each tool from the sidebar
  4. Check browser console for errors (should be none)

Test 3: Mobile Testing

  1. Open browser dev tools (F12)
  2. Switch to mobile device view
  3. Test responsive design on different screen sizes
  4. Verify all tools work on mobile

Test 4: Performance Testing

# Run performance audit
npm run lighthouse

🔧 Common Setup Issues

Port Already in Use

# Kill process on port 3000
lsof -ti:3000 | xargs kill -9

# Or use different port
npm run dev -- --port 3001

Node Module Issues

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

Build Errors

# Clear build cache
rm -rf dist
npm run build

📱 Mobile Development

Testing on Mobile Devices

  1. Connect mobile device to same WiFi network
  2. Find your IP address: ipconfig (Windows) or ifconfig (Mac/Linux)
  3. Access: http://YOUR_IP:3000 on mobile browser
  4. Add to home screen for app-like experience

Responsive Breakpoints

  • Mobile: 320px - 768px
  • Tablet: 768px - 1024px
  • Desktop: 1024px+

🚀 Production Deployment

Build for Production

# Build optimized version
npm run build

# Preview production build
npm run preview

# Deploy dist/ folder to your hosting provider

Environment Variables

Create .env.production:

VITE_APP_TITLE=WebDevToys
VITE_APP_VERSION=1.0.0

🛡️ Security Notes

  • JWT Tokens: Never enter real production secrets
  • Certificates: Use test certificates only
  • Images: No images are uploaded to servers (client-side only)
  • Data Privacy: All processing happens in your browser

🆘 Getting Help

Check Console Errors

  1. Open browser dev tools (F12)
  2. Look at Console tab for red error messages
  3. Check Network tab for failed requests

Common Solutions

  • Clear browser cache and reload
  • Try different browser (Chrome, Firefox, Safari)
  • Check internet connection for external resources
  • Disable ad blockers temporarily

Report Issues

  1. Check GitHub Issues for existing solutions
  2. Create new issue with:
    • Browser and version
    • Error messages from console
    • Steps to reproduce
    • Expected vs actual behavior

🎯 Next Steps

  1. Explore all tools - Try different input types and options
  2. Check performance - Run npm run lighthouse
  3. Run tests - Verify with npm test
  4. Contribute - See CONTRIBUTING.md for development guidelines
  5. Deploy - Build and deploy to your hosting provider

🎉 Congratulations! You're now ready to use WebDevToys Encoders/Decoders tools. Start exploring and let us know what you think!

Need more help? Check the full README.md for detailed documentation.