⚡ EnglishJs

A programming language that lets non-programmers create full-stack web applications using simple English-like syntax.

Write .english files, run them, and get a working web app — no HTML, CSS, or JavaScript knowledge required.

Quick Start

# Install dependencies
npm install

# Run an example
npx englishjs run examples/hello.english

# Run the Tailwind UI demo
npx englishjs run examples/example-ui.english

# Run the Todo demo (store + storage)
npx englishjs run examples/example-todo.english

# Or scaffold a new project (recommended)
npx @naved-uddin/englishjs new myApp
cd myApp
npx englishjs run app.english # or npm run dev

Scaffolding + updates

• englishjs new <projectName> now writes @naved-uddin/englishjs: "latest" in generated package.json
• This means npm install uses the latest published package
• npm update @naved-uddin/englishjs will also move to the latest dist-tag

VS Code syntax + icon

• Install extension: naved-uddin.englishjs
• Scaffolding now creates .vscode/extensions.json with that recommendation
• Scaffolding also adds .vscode/settings.json with *.english -> englishjs association

Aliases

This package exposes these binaries:

• englishjs
• create-englishjs
• create-english

CLI Commands

| Command | Purpose | |---|---| | englishjs new <projectName> | Scaffold a new EnglishJs app | | englishjs run <file.english> | Compile and run an app | | englishjs dev <file.english> | Run dev server with live reload | | englishjs build [file.english] | Production build bundle | | englishjs install <plugin> | Install plugin | | englishjs uninstall <plugin> | Remove plugin | | englishjs plugins | List installed plugins | | englishjs help | Show help |

Helpful npm scripts in this repo:

• npm run ui → runs examples/example-ui.english (Tailwind portfolio page demo)
• npm run todo → runs examples/example-todo.english (todo list with update/delete row actions + storage)
• npm run ai → runs examples/example-ai.english
• npm run router → runs examples/example-router.english

Language Rules

• Statements end with a dot: .
• Keywords are case-insensitive
• // ... comments are supported
• Basic arithmetic expressions are supported (+ - * /)

Full Syntax Reference (Current)

1) Input

Ask user and save

Ask me "What is your name?" and save as name.

Use case: get runtime input from user for later logic/UI rendering.

2) Output

Show literal

Show "Hello World".

Show variable / expression

Show name.
Show a + b.
Show 10 + 20.

Toast notification

Toast "Saved successfully".
Toast userEmail.
When contactBtn is clicked then Toast "Email: [email protected]".
Toast "Profile updated" at top center.

Toast position options:

• top left
• top center
• top right
• bottom left
• bottom center
• bottom right
• center

Use case: render messages, debug values, show computed results.

3) Variables

Set variable

Set age to 25.
Set greeting to "Hi".
Set isLoggedIn to true.
Set total to price + tax.

Use case: maintain local state and computed values.

4) Conditions

If statement

If age is greater than 18 then Show "Adult".
If count equals 0 then Show "Start".
If a is less than b then Show "A is smaller".
If isLoggedIn equals true then Show "Welcome".

Also supports do:

If age is greater than 18 do Show "Adult".

Use case: branching, validation, conditional UI behavior.

5) Repeat / Loop

Repeat 3 times, Show "Hello".
Repeat 5 times, Set count to count + 1.

Use case: iteration for repeated output or state updates.

6) Actions (Reusable logic)

Create action

Create action greet, Show "Hello".
Create action addTwo, Set sum to a + b.

Run / Call action

Run greet.
Call greet.
Run addTwo with a = 10 and b = 5.
Call addTwo with a = 10 and b = 5.

Use case: reuse logic, organize app behavior into named routines.

7) API Endpoints

Create endpoint

Create endpoint "/hello", Show "Hello API".
Create endpoint "/user", Show "User API".

Use case: expose server-side HTTP responses from EnglishJs code.

8) Storage (database/storage keywords)

Set username to "Alice".
Save username to database.
Load username from database.
Show username.

database and storage are interchangeable.

Use case: persist user/app data across sessions.

9) Global Stores

Create store

Create store userStore with name = "John" and loggedIn = true.
Create store userStore with name = "John" who is not loggedIn.

Update store

Update userStore.name to "Johny".
Update userStore's name to "Johny".
Update userStore age to 30.

Read store values

Show userStore.name.
Show name from userStore.

Use case: app-level shared state for UI and events.

10) UI Components

All are created using Create ... syntax.

Page

Create page "/" with background "#0f172a" and color "white".

Text / Title / Heading / Label

Create text "Hello".
Create title "Dashboard".
Create heading "Stats".
Create label "Username".

Button

Create button "Submit" called submitBtn.

Input

Create input called nameInput with placeholder "Enter name".

Container / Form

Create container called card with padding 16px.
Create form called loginForm with rounded 12px.

Image

Create image "https://example.com/logo.png" called logo.

Use case: build full UI declaratively without writing HTML/CSS directly.

11) UI Styling Syntax

You can use style phrases in Create ... with ... and in Set theme ....

Common properties include:

• color / text color
• background / background color
• font / font family
• size / font size
• width / height / min / max
• margin / padding / gap
• border / border color / rounded
• shadow / opacity / cursor

Shorthand helpers include:

• centered
• bold / italic / underline
• fullwidth / fullheight
• stack vertically / horizontally

Additional layout helpers include:

• relative / absolute / fixed / sticky
• flex row / flex column
• items start / items center / items end
• justify start / justify center / justify end / justify between / justify around / justify evenly
• text left / text center / text right
• rounded small / rounded medium / rounded large / rounded full

Tailwind utility classes (full power)

EnglishJs now supports direct Tailwind utility classes in plain-English style syntax.

Create button "Save" called saveBtn with tailwind classes "px-4 py-2 rounded-xl bg-sky-500 text-white hover:bg-sky-400".
Create container called card with class "p-6 bg-slate-800 border border-slate-700 rounded-2xl shadow-xl".
Create input called email with utility classes "w-full px-3 py-2 bg-slate-900 text-slate-100 border border-slate-600 rounded-lg".

Supported aliases for Tailwind utility input:

• tailwind
• tailwind class
• tailwind classes
• class / classes
• utility classes

Use case: quickly style components in plain language.

12) Theme

Set theme

Set theme to background "#0f172a", color "#e2e8f0" and font "Segoe UI".
Set theme to primary color "purple", accent color "cyan".

Supported special theme keys include:

• primary color
• accent color
• surface color
• border color

Use case: define app-wide visual defaults.

13) Events

When-event binding

When submitBtn is clicked then Show "Submitted".
When page loads then Show "Welcome".
When nameInput changes then Set name to nameInput.

Event words supported include (mapped internally):

• clicked / click / pressed
• changes / changed / change
• loads / loaded / load
• submit / submits / submitted
• hover / hovered
• enters / enter pressed
• focused / blurred
• double clicked

Use case: interactive UI behavior.

14) Routing & Navigation

Define routes inline

Create page "/".
Create page "/about".

Navigate

Go to "/about".
Navigate to "/".
When aboutBtn is clicked then go to "/about".

Use case: single-page app style navigation.

Route content from separate files (new)

Create page "/about" from "pages/about.english".
Create page "/contact" from "pages/contact.english" with background "#16213e".

This lets you keep large apps modular by route file.

15) AI Syntax

Ask AI

Ask AI to summarize JavaScript ecosystem changes.
Ask AI to search web latest updates about JavaScript ecosystem.
Ask AI to generate image for futuristic dashboard in blue neon style.
Ask AI to summarize this paragraph and save as summary.
Show summary.

Save AI response

Ask AI to explain closures and save as closureNotes.
Show closureNotes.

Use case: natural-language generation, summarization, local image generation, web lookup.

16) Expression Fallbacks

The expression plugin supports fallback expression parsing in bodies.

Example:

Create action sumMany, sum a and b and c.

Use case: concise arithmetic-style return flows.

Multi-file Routing Example

app.english

Set theme to background "navy" and color "white".

Create page "/" with background "navy".
Create title "Home".
Create button "Go to About" called aboutBtn.

Create page "/about" from "pages/about.english" with background "#1a1a2e".

When aboutBtn is clicked then go to "/about".

pages/about.english

Create title "About".
Create text "Loaded from external route file".
Create button "Back" called homeBtn.
When homeBtn is clicked then go to "/".

Use-Case Cookbook

• Form app: use Create form, Create input, When ... submit ..., Save ... to database.
• Dashboard: use Create page, Create title/text/container, stores, and theme.
• SPA website: use Create page "/...", Go to, and route file imports.
• API-backed tool: mix Create endpoint with UI pages.
• AI assistant app: use Ask AI ..., save outputs with save as, render via Show.

Current Project Structure

englishjs/
├── cli/                 # CLI entrypoint and command handlers
├── compiler/            # compile(source) => tokens + AST
├── parser/              # tokenizer + parser core
├── plugins/builtins/    # language syntax plugins
├── runtime/             # server-side executor/runtime core
├── client/              # browser runtime (UI/events/routes/AI/storage)
├── server/              # express server + HTML shell
├── dev/                 # dev server + file watcher + live reload
├── build/               # bundler/build pipeline
├── libs/                # browser libs (tailwind.js, puter.js)
├── storage/             # storage adapters / docs
├── sdk/                 # plugin SDK and installer
├── vscode-extension/     # VS Code language/icon extension source
├── examples/            # sample .english apps
└── package.json

Runtime Notes

• If port 3000 is occupied, server auto-falls to the next free port.
• In free AI mode, cloud SDK is not loaded by default.
• Route file imports are expanded at run/dev compile time.
• Generated HTML shell uses libs/tailwind.js for base visual styling.

License

MIT