npm - asjs-express - Versions diffs - 1.1.0 - Mend

asjs-express 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/LICENSE +21 -0
package/README.md +883 -0
package/index.js +1 -0
package/lib/asjs.js +1579 -0
package/lib/client/asjs-core.css +92 -0
package/lib/client/asjs-router.js +989 -0
package/lib/client/asjs-theme.css +1073 -0
package/package.json +63 -0

package/README.md ADDED Viewed

@@ -0,0 +1,883 @@
+# asjs-express
+ASJS is a lightweight Express view engine built for teams that still want the calm, readable side of server-rendered pages without giving up shared layouts, async page preparation, partials, and modern navigation behavior.
+Bu depo içindeki örnek yüzey ise WebAS adıyla anlatılıyor. Tonu bilerek daha gerçek tutuldu: gösterişten çok düzeni, süsten çok açıklığı, ilk izlenimden çok sürdürülebilirliği önemseyen bir yapı gibi kurgulandı.
+## English
+### Why this project exists
+ASJS was built for a very common problem in Express projects: pages start simple, then real work arrives. A dashboard needs data before render. A contact form needs validation and a meaningful response. A shared layout needs to stay stable while the inside changes. At that point, many projects either become repetitive or drift into a heavy front-end stack before they actually need one.
+ASJS keeps that middle ground clean. It gives you an EJS-like template syntax, a small but practical view model, optional client-side navigation, and the ability to finish your data work before the first HTML reaches the browser.
+The WebAS example in this repository is written in that spirit. It presents a small, believable interface structure shaped by two developers:
+- [Acarfx](https://acarfx.com)
+- [Seyfullah Kısacık](https://seyfooksck.com/)
+The intention is simple: this should read like something a careful team would actually maintain, not like a throwaway demo assembled for a screenshot.
+### What ASJS gives you
+- EJS-like syntax with `<% %>`, `<%= %>`, and `<%- %>`
+- Layout support without extra ceremony
+- Partial rendering with prop validation
+- Template caching
+- Built-in client router with transitions, prefetch, and loading bar support
+- Async form enhancement for marked forms
+- Plugin and hook support for Express projects that need to grow over time
+- Package-served assets, so you do not have to manually copy router files into your public folder
+### Install
+```bash
+npm install asjs-express
+```
+### Quick start
+```js
+const express = require('express')
+const { setupAsjs } = require('asjs-express')
+const app = express()
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  defaultLayout: 'layouts/main',
+  debug: true,
+  cache: true,
+  forms: true,
+  transitions: 'lift',
+  prefetch: true,
+  loadingBar: true
+})
+app.get('/', asjs.page('home', {
+  title: 'Hello ASJS'
+}))
+app.use(asjs.errors())
+app.listen(3000)
+```
+### Minimal Express template
+```js
+const express = require('express')
+const { setupAsjs } = require('asjs-express')
+const app = express()
+const asjs = setupAsjs(app, { rootDir: __dirname })
+app.get('/', asjs.page('home', { title: 'Hello ASJS' }))
+app.listen(3000)
+```
+### Layout usage
+```asjs
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <title><%= title %></title>
+    <%- asjs.clientTags({ preload: true, theme: true }) %>
+  </head>
+  <body<%- asjs.bodyAttrs() %>>
+    <%- asjs.progressMarkup() %>
+    <main<%- asjs.viewAttrs() %>>
+      <%- body %>
+    </main>
+  </body>
+</html>
+```
+`asjs.clientTags()` injects the built-in ASJS stylesheet and router script for you.
+`theme: true` optionally loads the packaged light, corporate WebAS theme.
+### Work before the page loads
+Yes. If you pass an async callback to `asjs.page()`, ASJS waits for that work to finish and only then calls `res.render(viewName, locals)`.
+That means database reads, API requests, permission checks, formatting, and view-model building can all happen before the browser receives the first HTML.
+#### Database example before render
+```js
+const db = {
+  companies: {
+    async findBySlug(slug) {
+      return { id: 7, slug, name: 'Northwind Studio' }
+    }
+  },
+  dashboards: {
+    async getMetrics(companyId) {
+      return [
+        { label: 'Open tasks', value: 12 },
+        { label: 'Active pages', value: 8 },
+        { label: 'Pending review', value: 3 }
+      ]
+    }
+  }
+}
+app.get('/dashboard/:slug', asjs.page('dashboard', async (req) => {
+  const company = await db.companies.findBySlug(req.params.slug)
+  const metrics = await db.dashboards.getMetrics(company.id)
+  return {
+    title: `${company.name} Dashboard`,
+    company,
+    metrics,
+    renderSummary: [
+      { label: 'Source', value: 'Database' },
+      { label: 'Company', value: company.name },
+      { label: 'Mode', value: 'Server render' }
+    ]
+  }
+}))
+```
+#### Returned page model
+The callback above returns a plain object like this:
+```js
+{
+  title: 'Northwind Studio Dashboard',
+  company: { id: 7, slug: 'northwind', name: 'Northwind Studio' },
+  metrics: [
+    { label: 'Open tasks', value: 12 },
+    { label: 'Active pages', value: 8 },
+    { label: 'Pending review', value: 3 }
+  ],
+  renderSummary: [
+    { label: 'Source', value: 'Database' },
+    { label: 'Company', value: 'Northwind Studio' },
+    { label: 'Mode', value: 'Server render' }
+  ]
+}
+```
+ASJS then turns that object into view locals and renders the final HTML.
+The browser does not receive a loading shell first and wait for the page model later. The work is already done.
+### Server-rendered POST example
+You can use the same pattern for POST routes when you want validation or save results to come back as a fully rendered page state.
+```js
+app.use(express.urlencoded({ extended: false }))
+app.post('/contact', asjs.page('contact', async (req) => {
+  const formValues = {
+    name: String(req.body.name || '').trim(),
+    email: String(req.body.email || '').trim(),
+    brief: String(req.body.brief || '').trim()
+  }
+  const formErrors = {}
+  if (!formValues.name) {
+    formErrors.name = 'Please enter a name.'
+  }
+  if (!formValues.email.includes('@')) {
+    formErrors.email = 'Please enter a valid email address.'
+  }
+  if (Object.keys(formErrors).length) {
+    return {
+      status: 422,
+      title: 'Contact',
+      formValues,
+      formErrors
+    }
+  }
+  const savedRecord = await saveProjectNote(formValues)
+  return {
+    title: 'Contact received',
+    submission: savedRecord
+  }
+}))
+```
+#### Validation return
+```js
+{
+  status: 422,
+  title: 'Contact',
+  formValues: {
+    name: '',
+    email: 'wrong-address',
+    brief: 'Need a redesign'
+  },
+  formErrors: {
+    name: 'Please enter a name.',
+    email: 'Please enter a valid email address.'
+  }
+}
+```
+#### Success return
+```js
+{
+  title: 'Contact received',
+  submission: {
+    reference: 'WEBAS-K3J9X2',
+    name: 'Lina Howard',
+    email: 'lina@northwind.dev',
+    brief: 'We need a cleaner delivery and dashboard structure.'
+  }
+}
+```
+In both cases, the route returns data. ASJS handles the render step after that.
+### Inline JSON response without leaving the page
+Sometimes you do not want a full page transition. You want to post to a dedicated route, get a short answer, and place that answer inside a specific panel.
+```asjs
+<form<%- asjs.formAttrs({
+  action: '/contact/availability',
+  method: 'post',
+  mode: 'json',
+  target: '#availability-response',
+  swap: 'replace'
+}) %>>
+  <input type="text" name="company" placeholder="Company name">
+  <input type="text" name="scope" placeholder="Dashboard, launch page, corporate site">
+  <button type="submit">Check route</button>
+</form>
+<div id="availability-response"></div>
+```
+```js
+app.post('/contact/availability', async (req, res) => {
+  const preview = await availabilityService.check(req.body)
+  res.json({
+    html: `
+      <div class="asjs-inline-response is-success">
+        <strong>${preview.title}</strong>
+        <p>${preview.message}</p>
+      </div>
+    `,
+    route: preview.route,
+    replyWindow: preview.replyWindow
+  })
+})
+```
+#### Example JSON response body
+```json
+{
+  "html": "<div class=\"asjs-inline-response is-success\"><strong>Northwind Studio can be routed into the operational track.</strong><p>The request can continue without leaving the current page shell.</p></div>",
+  "route": "Operational UI track",
+  "replyWindow": "1 business day"
+}
+```
+ASJS reads that response, finds `#availability-response`, and updates only that part of the page.
+### Plugins and hooks
+For projects that need room to grow, `setupAsjs()` now supports plugins and lifecycle hooks.
+```js
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  plugins: [
+    function studioPlugin(api) {
+      const healthRouter = api.express.Router()
+      healthRouter.get('/', (req, res) => {
+        res.json({ ok: true, service: 'studio-plugin' })
+      })
+      api.app.use('/health', healthRouter)
+      api.extendLocals({ supportEmail: 'team@example.com' })
+      api.addHook('beforeRender', ({ pageData }) => ({
+        pageData: {
+          ...pageData,
+          supportEmail: 'team@example.com'
+        }
+      }))
+    }
+  ]
+})
+```
+Available hook points:
+- `beforePage`
+- `afterPage`
+- `beforeRender`
+- `afterRender`
+### Form enhancement
+```asjs
+<form class="contact-form"<%- asjs.formAttrs({
+  action: '/contact',
+  method: 'post',
+  transition: 'slide'
+}) %>>
+  <input type="text" name="name" placeholder="Project lead">
+  <button type="submit">Send</button>
+</form>
+```
+`asjs.formAttrs()` marks a form for the built-in ASJS client handler.
+The response may come back as full HTML or as JSON for an inline target update.
+### Router lifecycle events
+- `asjs:before-navigate`
+- `asjs:content-replaced`
+- `asjs:navigated`
+- `asjs:navigation-error`
+- `asjs:before-submit`
+- `asjs:form-response`
+- `asjs:form-success`
+- `asjs:form-error`
+These events are useful for analytics, loading states, cleanup logic, and custom form feedback.
+### Component helper
+```js
+const asjs = setupAsjs(app, {
+  components: {
+    'partials/card': {
+      props: {
+        title: 'string',
+        text: 'string',
+        tone: {
+          type: 'string',
+          default: 'neutral'
+        }
+      },
+      strict: true
+    }
+  }
+})
+```
+```asjs
+<%- component('partials/card', { title: 'Card', text: 'Body text' }) %>
+```
+### Built-in asset delivery
+ASJS serves its client files from inside the package by default.
+- default mount path: `/_asjs`
+- router script: `/_asjs/asjs-router.js?v=...`
+- core stylesheet: `/_asjs/asjs-core.css?v=...`
+- optional theme stylesheet: `/_asjs/asjs-theme.css?v=...`
+The `v=...` query string is generated automatically for cache busting.
+### Transition presets
+- `fade`
+- `lift`
+- `slide`
+- `scale`
+- `blur-soft`
+Use them globally with `transitions`, per-page with `transition`, or per-link with `data-asjs-transition`.
+### Highlights
+- `setupAsjs(app, options)` integrates directly into an existing Express app.
+- `component()` validates props before rendering a partial.
+- `cache: true` keeps compiled templates until file mtimes change.
+- `prefetch` and `loadingBar` improve navigation feel.
+- `forms: true` enables built-in async form enhancement.
+- `plugins` opens room for middleware, routes, and project-specific services.
+- `assetVersion` lets you override or disable cache-busting.
+- `serveClientAssets` serves router assets from the package itself.
+### Package utilities
+```js
+const { getAsjsPackagePaths } = require('asjs-express')
+const paths = getAsjsPackagePaths()
+console.log(paths.routerPath)
+```
+### Local demo
+```bash
+npm install
+npm run example:express
+```
+Open `http://localhost:3001`.
+### Repository example app
+The repository ships a dedicated Express example under `example-express/`.
+- entry: `example-express/app.js`
+- favicon: `example-express/favicon.svg`
+- views: `example-express/views`
+- start command: `npm run example:express`
+- starter pages: `/`, `/dashboard`, `/products`, `/contact`
+- plugin health route: `/webas-platform/health`
+The example presents WebAS as a practical interface structure associated with [Acarfx](https://acarfx.com) and [Seyfullah Kısacık](https://seyfooksck.com/). It is intentionally written with a calm, professional tone because the project is meant to feel usable, not theatrical.
+## Türkçe
+### Bu proje neden var?
+ASJS, Express projelerinde çok sık karşılaşılan ama çoğu zaman gereksiz yere karmaşık hâle gelen bir alan için yazıldı: sayfalar ilk gün sade olur, sonra gerçek ihtiyaçlar gelir. Dashboard verisi gerekir. Form doğrulaması gerekir. Aynı layout içinde farklı sayfaları sakin biçimde taşımak gerekir. Bir noktadan sonra ya aynı kod tekrar eder ya da ihtiyaç o kadar büyük değilken proje ağır bir ön yüz yapısına sürüklenir.
+ASJS tam burada devreye girer. Sunucu tarafını sade tutar, şablon katmanını EJS benzeri bir yapıda bırakır, istersen sayfa geçişlerini güçlendirir, istersen hiçbir şeyi zorlamaz. En önemlisi de şu soruya net cevap verir: Evet, sayfa yüklenmeden önce veriyi hazırlayabilirsin.
+Bu depodaki WebAS örneği de bu anlayışla yazıldı. Dili özellikle daha insanî ve daha gerçek tutuldu. Amaç “vitrinlik demo” hissi vermek değil, gerçekten çalışan küçük bir ekibin kullanabileceği bir yapı duygusu vermekti.
+Bu örnek anlatımın arkasında iki geliştirici adı özellikle görünür tutuluyor:
+- [Acarfx](https://acarfx.com)
+- [Seyfullah Kısacık](https://seyfooksck.com/)
+WebAS yüzeyi, bu iki geliştiricinin birlikte şekillendirdiği düzenli, açık ve kurumsal bir arayüz dili gibi anlatılıyor. Çünkü iyi bir arayüz çoğu zaman bağırmaz; düzeniyle güven verir.
+### ASJS neler sağlar?
+- `<% %>`, `<%= %>`, `<%- %>` tabanlı EJS benzeri sözdizimi
+- Ek yük bindirmeyen layout desteği
+- Prop doğrulamalı partial ve component kullanımı
+- Template cache
+- Geçiş, prefetch ve loading bar destekli istemci yönlendirmesi
+- İşaretli formlar için dahili async form akışı
+- Büyüyen Express projeleri için plugin ve hook desteği
+- Public klasöre dosya kopyalamadan paket içinden asset servisi
+### Kurulum
+```bash
+npm install asjs-express
+```
+### Hızlı başlangıç
+```js
+const express = require('express')
+const { setupAsjs } = require('asjs-express')
+const app = express()
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  defaultLayout: 'layouts/main',
+  debug: true,
+  cache: true,
+  forms: true,
+  transitions: 'lift',
+  prefetch: true,
+  loadingBar: true
+})
+app.get('/', asjs.page('home', {
+  title: 'Merhaba ASJS'
+}))
+app.use(asjs.errors())
+app.listen(3000)
+```
+### Minimal Express şablonu
+```js
+const express = require('express')
+const { setupAsjs } = require('asjs-express')
+const app = express()
+const asjs = setupAsjs(app, { rootDir: __dirname })
+app.get('/', asjs.page('home', { title: 'Merhaba ASJS' }))
+app.listen(3000)
+```
+### Layout kullanımı
+```asjs
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <title><%= title %></title>
+    <%- asjs.clientTags({ preload: true, theme: true }) %>
+  </head>
+  <body<%- asjs.bodyAttrs() %>>
+    <%- asjs.progressMarkup() %>
+    <main<%- asjs.viewAttrs() %>>
+      <%- body %>
+    </main>
+  </body>
+</html>
+```
+`asjs.clientTags()` çağrısı dahili ASJS stil ve router etiketlerini otomatik üretir.
+`theme: true` ise açık renkli, kurumsal WebAS temasını yükler.
+### Sayfa yüklenmeden önce işlem yapmak
+Evet, mümkün. `asjs.page()` içine async bir callback verirsen ASJS bu işlemin bitmesini bekler, ardından `res.render(viewName, locals)` çağrısını yapar.
+Yani veritabanı sorgusu, API isteği, yetki kontrolü, veri biçimlendirme ve view model oluşturma gibi işler ilk HTML tarayıcıya gitmeden önce tamamlanabilir.
+#### Render öncesi veritabanı örneği
+```js
+const db = {
+  companies: {
+    async findBySlug(slug) {
+      return { id: 7, slug, name: 'Northwind Studio' }
+    }
+  },
+  dashboards: {
+    async getMetrics(companyId) {
+      return [
+        { label: 'Açık görev', value: 12 },
+        { label: 'Aktif sayfa', value: 8 },
+        { label: 'Onay bekleyen', value: 3 }
+      ]
+    }
+  }
+}
+app.get('/dashboard/:slug', asjs.page('dashboard', async (req) => {
+  const company = await db.companies.findBySlug(req.params.slug)
+  const metrics = await db.dashboards.getMetrics(company.id)
+  return {
+    title: `${company.name} Dashboard`,
+    company,
+    metrics,
+    renderSummary: [
+      { label: 'Kaynak', value: 'Veritabanı' },
+      { label: 'Şirket', value: company.name },
+      { label: 'Mod', value: 'Sunucu render' }
+    ]
+  }
+}))
+```
+#### Dönen sayfa modeli
+Yukarıdaki callback şu tipte bir nesne döndürür:
+```js
+{
+  title: 'Northwind Studio Dashboard',
+  company: { id: 7, slug: 'northwind', name: 'Northwind Studio' },
+  metrics: [
+    { label: 'Açık görev', value: 12 },
+    { label: 'Aktif sayfa', value: 8 },
+    { label: 'Onay bekleyen', value: 3 }
+  ],
+  renderSummary: [
+    { label: 'Kaynak', value: 'Veritabanı' },
+    { label: 'Şirket', value: 'Northwind Studio' },
+    { label: 'Mod', value: 'Sunucu render' }
+  ]
+}
+```
+ASJS bu nesneyi view locals hâline getirir ve nihai HTML’i üretir.
+Tarayıcı önce boş bir iskelet alıp sonra veriyi beklemez. Veri işi zaten tamamlanmıştır.
+### Server-rendered POST dönüşü
+POST rotalarında da aynı yaklaşımı kullanabilirsin. Özellikle form doğrulaması, kayıt sonucu veya başarı ekranı aynı view içinde geri dönecekse bu çok temiz çalışır.
+```js
+app.use(express.urlencoded({ extended: false }))
+app.post('/contact', asjs.page('contact', async (req) => {
+  const formValues = {
+    name: String(req.body.name || '').trim(),
+    email: String(req.body.email || '').trim(),
+    brief: String(req.body.brief || '').trim()
+  }
+  const formErrors = {}
+  if (!formValues.name) {
+    formErrors.name = 'Lütfen bir isim girin.'
+  }
+  if (!formValues.email.includes('@')) {
+    formErrors.email = 'Lütfen geçerli bir e-posta adresi girin.'
+  }
+  if (Object.keys(formErrors).length) {
+    return {
+      status: 422,
+      title: 'İletişim',
+      formValues,
+      formErrors
+    }
+  }
+  const savedRecord = await saveProjectNote(formValues)
+  return {
+    title: 'İletişim alındı',
+    submission: savedRecord
+  }
+}))
+```
+#### Hatalı dönüş örneği
+```js
+{
+  status: 422,
+  title: 'İletişim',
+  formValues: {
+    name: '',
+    email: 'yanlis-adres',
+    brief: 'Tasarım yenilemesi istiyoruz'
+  },
+  formErrors: {
+    name: 'Lütfen bir isim girin.',
+    email: 'Lütfen geçerli bir e-posta adresi girin.'
+  }
+}
+```
+#### Başarılı dönüş örneği
+```js
+{
+  title: 'İletişim alındı',
+  submission: {
+    reference: 'WEBAS-K3J9X2',
+    name: 'Lina Howard',
+    email: 'lina@northwind.dev',
+    brief: 'Daha temiz bir teslim ve dashboard yapısı istiyoruz.'
+  }
+}
+```
+Her iki durumda da rota veri döndürür. Render adımını ASJS sonradan kendisi yürütür.
+### Sayfadan ayrılmadan JSON döndürmek
+Bazen tam sayfa geçişi istemezsin. Belirli bir rotaya POST atıp kısa bir cevap almak ve yalnızca tek bir paneli güncellemek istersin.
+```asjs
+<form<%- asjs.formAttrs({
+  action: '/contact/availability',
+  method: 'post',
+  mode: 'json',
+  target: '#availability-response',
+  swap: 'replace'
+}) %>>
+  <input type="text" name="company" placeholder="Şirket adı">
+  <input type="text" name="scope" placeholder="Dashboard, lansman sayfası, kurumsal site">
+  <button type="submit">Rotayı kontrol et</button>
+</form>
+<div id="availability-response"></div>
+```
+```js
+app.post('/contact/availability', async (req, res) => {
+  const preview = await availabilityService.check(req.body)
+  res.json({
+    html: `
+      <div class="asjs-inline-response is-success">
+        <strong>${preview.title}</strong>
+        <p>${preview.message}</p>
+      </div>
+    `,
+    route: preview.route,
+    replyWindow: preview.replyWindow
+  })
+})
+```
+#### Örnek JSON cevap gövdesi
+```json
+{
+  "html": "<div class=\"asjs-inline-response is-success\"><strong>Northwind Studio operasyon hattına yönlendirilebilir.</strong><p>İstek mevcut sayfa kabuğu bozulmadan devam edebilir.</p></div>",
+  "route": "Operasyonel arayüz hattı",
+  "replyWindow": "1 iş günü"
+}
+```
+ASJS bu cevabı okur, `#availability-response` alanını bulur ve yalnızca o kısmı günceller.
+### Plugin ve hook yapısı
+Proje büyüdüğünde `setupAsjs()` artık plugin ve yaşam döngüsü hook’ları için de alan açar.
+```js
+const asjs = setupAsjs(app, {
+  rootDir: __dirname,
+  plugins: [
+    function studioPlugin(api) {
+      const healthRouter = api.express.Router()
+      healthRouter.get('/', (req, res) => {
+        res.json({ ok: true, service: 'studio-plugin' })
+      })
+      api.app.use('/health', healthRouter)
+      api.extendLocals({ supportEmail: 'team@example.com' })
+      api.addHook('beforeRender', ({ pageData }) => ({
+        pageData: {
+          ...pageData,
+          supportEmail: 'team@example.com'
+        }
+      }))
+    }
+  ]
+})
+```
+Kullanılabilen hook noktaları:
+- `beforePage`
+- `afterPage`
+- `beforeRender`
+- `afterRender`
+### Form geliştirme
+```asjs
+<form class="contact-form"<%- asjs.formAttrs({
+  action: '/contact',
+  method: 'post',
+  transition: 'slide'
+}) %>>
+  <input type="text" name="name" placeholder="Proje sorumlusu">
+  <button type="submit">Gönder</button>
+</form>
+```
+`asjs.formAttrs()` bir formu dahili ASJS istemci akışı için işaretler.
+Gelen cevap tam HTML de olabilir, belirli bir hedef alanı güncelleyen JSON da olabilir.
+### Router yaşam döngüsü event’leri
+- `asjs:before-navigate`
+- `asjs:content-replaced`
+- `asjs:navigated`
+- `asjs:navigation-error`
+- `asjs:before-submit`
+- `asjs:form-response`
+- `asjs:form-success`
+- `asjs:form-error`
+Bu event’ler loading durumları, analytics, arayüz temizliği ve özel form geri bildirimi için işe yarar.
+### Component helper
+```js
+const asjs = setupAsjs(app, {
+  components: {
+    'partials/card': {
+      props: {
+        title: 'string',
+        text: 'string',
+        tone: {
+          type: 'string',
+          default: 'neutral'
+        }
+      },
+      strict: true
+    }
+  }
+})
+```
+```asjs
+<%- component('partials/card', { title: 'Kart', text: 'İçerik' }) %>
+```
+### Dahili asset servisi
+ASJS istemci dosyalarını varsayılan olarak paketin içinden servis eder.
+- varsayılan mount path: `/_asjs`
+- router script: `/_asjs/asjs-router.js?v=...`
+- ana stil dosyası: `/_asjs/asjs-core.css?v=...`
+- opsiyonel tema dosyası: `/_asjs/asjs-theme.css?v=...`
+`v=...` query parametresi otomatik cache-busting için üretilir.
+### Geçiş preset’leri
+- `fade`
+- `lift`
+- `slide`
+- `scale`
+- `blur-soft`
+Bunları global olarak `transitions`, sayfa bazında `transition`, link bazında ise `data-asjs-transition` ile kullanabilirsin.
+### Öne çıkanlar
+- `setupAsjs(app, options)` mevcut Express uygulamasına doğrudan bağlanır.
+- `component()` partial render etmeden önce props doğrular.
+- `cache: true` derlenmiş template’leri dosya mtime değişene kadar saklar.
+- `prefetch` ve `loadingBar` geçiş hissini güçlendirir.
+- `forms: true` işaretli formlar için dahili async form akışını açar.
+- `plugins` middleware, route ve servis katmanı için alan bırakır.
+- `assetVersion` ile dahili asset versiyonlamasını ezebilir veya kapatabilirsin.
+- `serveClientAssets` router asset’lerini doğrudan paket içinden servis eder.
+### Paket yardımcıları
+```js
+const { getAsjsPackagePaths } = require('asjs-express')
+const paths = getAsjsPackagePaths()
+console.log(paths.routerPath)
+```
+### Lokal demo
+```bash
+npm install
+npm run example:express
+```
+Tarayıcıda `http://localhost:3001` adresini aç.
+### Repodaki örnek uygulama
+Repo içinde ayrı bir Express örneği `example-express/` altında durur.
+- giriş: `example-express/app.js`
+- favicon: `example-express/favicon.svg`
+- view klasörü: `example-express/views`
+- çalıştırma komutu: `npm run example:express`
+- başlangıç rotaları: `/`, `/dashboard`, `/products`, `/contact`
+- plugin sağlık rotası: `/webas-platform/health`
+Bu örnek, WebAS’i [Acarfx](https://acarfx.com) ve [Seyfullah Kısacık](https://seyfooksck.com/) ile ilişkilendirilen düzenli ve kurumsal bir arayüz dili gibi sunar. Bu ton bilinçli seçildi. Çünkü bazı projelerde asıl değer, daha çok şey göstermek değil, daha çok şeyi sakin biçimde taşıyabilmektir.