npm package: @naved-uddin/englishjs
Description: A programming language that lets non-programmers create full stack web apps using simple English-like syntax.
Author: Naved Uddin
Latest version: 2.3.2

# ⚡ 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

```bash
# 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

```english
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

```english
Show "Hello World".
```

### Show variable / expression

```english
Show name.
Show a + b.
Show 10 + 20.
```

### Toast notification

```english
Toast "Saved successfully".
Toast userEmail.
When contactBtn is clicked then Toast "Email: hello@example.com".
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

```english
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

```english
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`:

```english
If age is greater than 18 do Show "Adult".
```

**Use case:** branching, validation, conditional UI behavior.

---

## 5) Repeat / Loop

```english
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

```english
Create action greet, Show "Hello".
Create action addTwo, Set sum to a + b.
```

### Run / Call action

```english
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

```english
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)

```english
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

```english
Create store userStore with name = "John" and loggedIn = true.
Create store userStore with name = "John" who is not loggedIn.
```

### Update store

```english
Update userStore.name to "Johny".
Update userStore's name to "Johny".
Update userStore age to 30.
```

### Read store values

```english
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

```english
Create page "/" with background "#0f172a" and color "white".
```

### Text / Title / Heading / Label

```english
Create text "Hello".
Create title "Dashboard".
Create heading "Stats".
Create label "Username".
```

### Button

```english
Create button "Submit" called submitBtn.
```

### Input

```english
Create input called nameInput with placeholder "Enter name".
```

### Container / Form

```english
Create container called card with padding 16px.
Create form called loginForm with rounded 12px.
```

### Image

```english
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.

```english
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

```english
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

```english
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

```english
Create page "/".
Create page "/about".
```

### Navigate

```english
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)

```english
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

```english
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

```english
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:

```english
Create action sumMany, sum a and b and c.
```

**Use case:** concise arithmetic-style return flows.

---

## Multi-file Routing Example

`app.english`

```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`

```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

```text
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