Evernote local dev loop

Evernote Local Dev Loop

Overview

Configure an efficient local development environment for Evernote API integration with sandbox testing, hot reload, ENML helpers, and a local Express server for OAuth testing.

Prerequisites

• Completed evernote-install-auth setup
• Node.js 18+ or Python 3.10+
• Evernote sandbox account at https://sandbox.evernote.com

Instructions

Step 1: Project Structure

Organize your project with clear separation of concerns:

evernote-app/
  src/
    services/       # NoteService, SearchService, etc.
    utils/          # ENML helpers, query builder
    middleware/     # Auth, rate limiting
  test/             # Unit and integration tests
  scripts/          # Dev utilities (test-connection, seed-data)
  .env.development  # Sandbox credentials
  .env.production   # Production credentials (gitignored)

Step 2: Environment Configuration

Create .env.development with sandbox credentials. Use a Developer Token for quick iteration (skip OAuth during development). Add .env* to .gitignore.

# .env.development
EVERNOTE_CONSUMER_KEY=your-sandbox-key
EVERNOTE_CONSUMER_SECRET=your-sandbox-secret
EVERNOTE_DEV_TOKEN=your-developer-token
EVERNOTE_SANDBOX=true
NODE_ENV=development
PORT=3000

Step 3: Evernote Client Wrapper

Create a client factory that switches between Developer Token (for scripts and tests) and OAuth (for the web app) based on environment configuration.

function createClient() {
  if (process.env.EVERNOTE_DEV_TOKEN) {
    return new Evernote.Client({
      token: process.env.EVERNOTE_DEV_TOKEN,
      sandbox: true
    });
  }
  return new Evernote.Client({
    consumerKey: process.env.EVERNOTE_CONSUMER_KEY,
    consumerSecret: process.env.EVERNOTE_CONSUMER_SECRET,
    sandbox: process.env.EVERNOTE_SANDBOX === 'true'
  });
}

Step 4: ENML Utility Helpers

Build helper functions: wrapInENML(html), textToENML(text), htmlToENML(html) (strip forbidden elements), and validateENML(content). These prevent BAD_DATA_FORMAT errors during development.

Step 5: Express Server with OAuth

Set up a local Express server with session management for OAuth flow testing. Include routes for /auth/start (get request token), /auth/callback (exchange for access token), and /dashboard (authenticated operations).

Step 6: Quick Test Script

Create a scripts/test-connection.js that verifies SDK setup by calling userStore.getUser() and noteStore.listNotebooks(). Run with node scripts/test-connection.js.

For the full project setup, Express server, ENML utilities, and test scripts, see Implementation Guide.

Output

• Project structure with services, utils, and middleware directories
• Environment configuration for sandbox and production
• Client factory with Developer Token and OAuth support
• ENML utility library (wrap, convert, validate)
• Express server with OAuth flow for local testing
• Connection test script for quick verification

Error Handling

Error	Cause	Solution
EVERNOTE_DEV_TOKEN not set	Missing dev token	Get from sandbox.evernote.com/api/DeveloperToken.action
Invalid consumer key	Wrong sandbox vs production key	Verify EVERNOTE_SANDBOX matches your key type
Session undefined	Missing express-session middleware	Install and configure express-session
Port already in use	Another process on port 3000	Change PORT in .env or kill the process

Resources

• Sandbox Environment
• Developer Tokens
• OAuth Guide

Next Steps

Proceed to evernote-sdk-patterns for advanced SDK usage patterns.

Examples

Quick sandbox test: Set EVERNOTE_DEV_TOKEN, run node scripts/test-connection.js to verify authentication, then create a test note using the Developer Token shortcut.

Full OAuth loop: Start the Express server, navigate to http://localhost:3000/auth/start, complete the Evernote authorization, and verify the access token is stored in the session.