5da08e7a.1f4c9eb5.js

"use strict";(self.webpackChunkadminforth=self.webpackChunkadminforth||[]).push([[6914],{6042:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>a,default:()=>h,frontMatter:()=>o,metadata:()=>i,toc:()=>d});const i=JSON.parse('{"id":"tutorial/hello-world","title":"Hello world app without CLI","description":"While AdminForth CLI is the fastest way to create a new project, you can also create a new project manually.","source":"@site/docs/tutorial/01-helloWorld.md","sourceDirName":"tutorial","slug":"/tutorial/hello-world","permalink":"/docs/tutorial/hello-world","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":1,"frontMatter":{"id":"hello-world","title":"Hello world app without CLI","sidebar_class_name":"hidden-sidebar"},"sidebar":"tutorialSidebar","previous":{"title":"Getting Started","permalink":"/docs/tutorial/gettingStarted"},"next":{"title":"Glossary","permalink":"/docs/tutorial/glossary"}}');var r=t(4848),s=t(8453);const o={id:"hello-world",title:"Hello world app without CLI",sidebar_class_name:"hidden-sidebar"},a="Hello world app without CLI",l={},d=[{value:"Prerequisites",id:"prerequisites",level:2},{value:"Installation",id:"installation",level:2},{value:"Environment variables",id:"environment-variables",level:2},{value:"Setting up the scripts",id:"setting-up-the-scripts",level:2},{value:"Database creation",id:"database-creation",level:2},{value:"Setting up AdminForth",id:"setting-up-adminforth",level:2},{value:"Initializing custom directory",id:"initializing-custom-directory",level:2},{value:"Possible configuration options",id:"possible-configuration-options",level:2}];function c(e){const n={a:"a",blockquote:"blockquote",code:"code",h1:"h1",h2:"h2",header:"header",img:"img",li:"li",ol:"ol",p:"p",pre:"pre",ul:"ul",...(0,s.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.header,{children:(0,r.jsx)(n.h1,{id:"hello-world-app-without-cli",children:"Hello world app without CLI"})}),"\n",(0,r.jsx)(n.p,{children:"While AdminForth CLI is the fastest way to create a new project, you can also create a new project manually."}),"\n",(0,r.jsx)(n.p,{children:"This might help you better understand how AdminForth project is structured and how to customize it."}),"\n",(0,r.jsx)(n.p,{children:"Here we create database with users and posts tables and admin panel for it."}),"\n",(0,r.jsx)(n.p,{children:"Users table will be used to store a credentials for login into admin panel itself."}),"\n",(0,r.jsxs)(n.p,{children:["When back-office user creates a new post it will be automatically assigned using ",(0,r.jsx)(n.code,{children:"authorId"})," to the user who created it."]}),"\n",(0,r.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,r.jsxs)(n.p,{children:["We will use Node v20 for this demo. If you have other Node versions, we recommend using ",(0,r.jsx)(n.a,{href:"https://github.com/nvm-sh/nvm?tab=readme-ov-file#install--update-script",children:"NVM"})," to switch them easily:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"nvm install 20\nnvm alias default 20\nnvm use 20\n"})}),"\n",(0,r.jsx)(n.h2,{id:"installation",children:"Installation"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"mkdir af-hello\ncd af-hello\nnpm init -y\nnpm i adminforth express @types/express typescript tsx @types/node -D\nnpx --yes tsc --init --module NodeNext --target ESNext\n"})}),"\n",(0,r.jsx)(n.h2,{id:"environment-variables",children:"Environment variables"}),"\n",(0,r.jsx)(n.p,{children:"Create two files in your project's root directory:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.code,{children:".env.local"})," \u2014 Place your non-sensitive environment variables here (e.g., local database paths, default configurations). This file can be safely committed to your repository as a demo or template configuration."]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.code,{children:".env"})," \u2014 Store sensitive tokens and secrets here (for example, ",(0,r.jsx)(n.code,{children:"ADMINFORTH_SECRET"})," and other private keys). Ensure that ",(0,r.jsx)(n.code,{children:".env"})," is added to your ",(0,r.jsx)(n.code,{children:".gitignore"})," to prevent accidentally committing sensitive data."]}),"\n"]}),"\n",(0,r.jsxs)(n.p,{children:["Put the following content to the ",(0,r.jsx)(n.code,{children:".env.local"})," file:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",metastring:'title="./.env.local"',children:"ADMINFORTH_SECRET=123\nNODE_ENV=development\nDATABASE_FILE=../db.sqlite\nDATABASE_FILE_URL=file:${DATABASE_FILE}\n"})}),"\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsx)(n.p,{children:"\u261d\ufe0f Production best practices:"}),"\n",(0,r.jsxs)(n.ol,{children:["\n",(0,r.jsxs)(n.li,{children:["Most likely you not need ",(0,r.jsx)(n.code,{children:".env"})," file at all, instead you should use environment variables (from Docker, Kubernetes, Operating System, etc.)"]}),"\n",(0,r.jsxs)(n.li,{children:["Set ",(0,r.jsx)(n.code,{children:"NODE_ENV"})," to ",(0,r.jsx)(n.code,{children:"production"})," in your deployment environment to optimize performance and disable development features like hot reloading."]}),"\n",(0,r.jsxs)(n.li,{children:["You should generate very unique value ",(0,r.jsx)(n.code,{children:"ADMINFORTH_SECRET"})," and store it in Vault or other secure place."]}),"\n"]}),"\n"]}),"\n",(0,r.jsx)(n.h2,{id:"setting-up-the-scripts",children:"Setting up the scripts"}),"\n",(0,r.jsxs)(n.p,{children:["Open ",(0,r.jsx)(n.code,{children:"package.json"})," and add the following scripts:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-json",metastring:'title="./package.json"',children:'{\n  ...\n//diff-add\n  "type": "module",\n  "scripts": {\n    ...\n//diff-add\n    "env": "dotenvx run -f .env.local -f .env --overload --",\n//diff-add\n    "start": "npm run env -- tsx watch index.ts",\n//diff-add\n    "migrateLocal": "npm run env -- npx prisma migrate deploy",\n//diff-add\n    "makemigration": "npm run env -- npx --yes prisma migrate deploy; npm run env -- npx --yes prisma migrate dev",\n  },\n}\n'})}),"\n",(0,r.jsx)(n.h2,{id:"database-creation",children:"Database creation"}),"\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsx)(n.p,{children:"\u261d\ufe0f For demo purposes we will create a database using Prisma and SQLite.\nYou can also create it using any other favorite tool or ORM and skip this step."}),"\n"]}),"\n",(0,r.jsxs)(n.p,{children:["Create ",(0,r.jsx)(n.code,{children:"./schema.prisma"})," and put next content there:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-text",metastring:'title="./schema.prisma"',children:'generator client {\n  provider = "prisma-client-js"\n}\n\ndatasource db {\n  provider = "sqlite"\n  url      = env("DATABASE_FILE_URL")\n}\n\nmodel User {\n  id           String     @id\n  createdAt    DateTime\n  email        String   @unique\n  role         String\n  passwordHash String\n  posts        Post[]\n}\n\nmodel Post {\n  id        String     @id\n  createdAt DateTime\n  title     String\n  content   String?\n  published Boolean\n  author    User?    @relation(fields: [authorId], references: [id])\n  authorId  String?\n}\n\n'})}),"\n",(0,r.jsxs)(n.p,{children:["Create database using ",(0,r.jsx)(n.code,{children:"prisma migrate"}),":"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"npm run makemigration --name init\n"})}),"\n",(0,r.jsx)(n.h2,{id:"setting-up-adminforth",children:"Setting up AdminForth"}),"\n",(0,r.jsxs)(n.p,{children:["Create ",(0,r.jsx)(n.code,{children:"index.ts"})," file in root directory with following content:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-ts",metastring:'title="./index.ts"',children:"import express from 'express';\nimport AdminForth, { AdminForthDataTypes, AdminUser, Filters } from 'adminforth';\n\nexport const admin = new AdminForth({\n  baseUrl: '',\n  auth: {\n    usersResourceId: 'adminuser',  // resource to get user during login\n    usernameField: 'email',  // field where username is stored, should exist in resource\n    passwordHashField: 'passwordHash',\n  },\n  customization: {\n    brandName: 'My Admin',\n    datesFormat: 'D MMM YY',\n    timeFormat: 'HH:mm:ss',\n    emptyFieldPlaceholder: '-',\n  },\n  dataSources: [{\n    id: 'maindb',\n    url: `sqlite://${process.env.DATABASE_FILE}`,\n  }],\n  resources: [\n    {\n      dataSource: 'maindb',\n      table: 'adminuser',\n      resourceId: 'adminuser',\n      label: 'Users',\n      recordLabel: (r: any) => `\ud83d\udc64 ${r.email}`,\n      columns: [\n        {\n          name: 'id',\n          primaryKey: true,\n          fillOnCreate: () => Math.random().toString(36).substring(7),\n          showIn: {\n            edit: false,\n            create: false,\n          },\n        },\n        {\n          name: 'email',\n          required: true,\n          isUnique: true,\n          enforceLowerCase: true,\n          validation: [\n            AdminForth.Utils.EMAIL_VALIDATOR,\n          ]\n        },\n        {\n          name: 'createdAt',\n          type: AdminForthDataTypes.DATETIME,\n          showIn: {\n            edit: false,\n            create: false,\n          },\n          fillOnCreate: () => (new Date()).toISOString(),\n        },\n        {\n          name: 'role',\n          enum: [\n            { value: 'superadmin', label: 'Super Admin' },\n            { value: 'user', label: 'User' },\n          ]\n        },\n        {\n          name: 'password',\n          virtual: true,\n          required: { create: true },\n          editingNote: { edit: 'Leave empty to keep password unchanged' },\n          minLength: 8,\n          type: AdminForthDataTypes.STRING,\n          showIn: {\n            show: false,\n            list: false,\n            filter: false,\n          },\n          masked: true,\n        },\n        { name: 'passwordHash', backendOnly: true, showIn: { all: false } }\n      ],\n    },\n    {\n      table: 'post',\n      resourceId: 'posts',\n      dataSource: 'maindb',\n      label: 'Posts',\n      recordLabel: (r: any) => `\ud83d\udcdd ${r.title}`,\n      columns: [\n        {\n          name: 'id',\n          primaryKey: true,\n          fillOnCreate: () => Math.random().toString(36).substring(7),\n          showIn: {\n            edit: false,\n            create: false,\n          },\n        },\n        {\n          name: 'title',\n          type: AdminForthDataTypes.STRING,\n          required: true,\n          showIn: { all: true },\n          maxLength: 255,\n          minLength: 3,\n        },\n        {\n          name: 'content',\n          showIn: { all: true },\n        },\n        {\n          name: 'createdAt',\n          showIn: {\n            edit: false,\n            create: false,\n          },\n          fillOnCreate: () => (new Date()).toISOString(),\n        },\n        {\n          name: 'published',\n          required: true,\n        },\n        {\n          name: 'authorId',\n          foreignResource: {\n            resourceId: 'adminuser',\n          },\n          showIn: {\n            edit: false,\n            create: false,\n          },\n          fillOnCreate: ({ adminUser }: { adminUser: AdminUser }) => {\n            return adminUser.dbUser.id;\n          }\n        }\n      ],\n    }\n  ],\n  menu: [\n    {\n      label: 'Core',\n      icon: 'flowbite:brain-solid', // any icon from iconify supported in format <setname>:<icon>, e.g. from here https://icon-sets.iconify.design/flowbite/\n      open: true,\n      children: [\n        {\n          homepage: true,\n          label: 'Posts',\n          icon: 'flowbite:home-solid',\n          resourceId: 'posts',\n        },\n      ]\n    },\n    { type: 'gap' },\n    { type: 'divider' },\n    { type: 'heading', label: 'SYSTEM' },\n    {\n      label: 'Users',\n      icon: 'flowbite:user-solid',\n      resourceId: 'adminuser',\n    }\n  ],\n});\n\n\nif (import.meta.url === `file://${process.argv[1]}`) {\n  // if script is executed directly e.g. node index.ts or npm start\n\n  const app = express()\n  app.use(express.json());\n  const port = 3500;\n\n  // needed to compile SPA. Call it here or from a build script e.g. in Docker build time to reduce downtime\n  await admin.bundleNow({ hotReload: process.env.NODE_ENV === 'development' });\n  console.log('Bundling AdminForth done. For faster serving consider calling bundleNow() from a build script.');\n\n  // serve after you added all api\n  admin.express.serve(app)\n\n  admin.discoverDatabases().then(async () => {\n    if (!await admin.resource('adminuser').get([Filters.EQ('email', 'adminforth')])) {\n      await admin.resource('adminuser').create({\n        email: 'adminforth',\n        passwordHash: await AdminForth.Utils.generatePasswordHash('adminforth'),\n        role: 'superadmin',\n      });\n    }\n  });\n\n  admin.express.listen(port, () => {\n    console.log(`\\n\u26a1 AdminForth is available at http://localhost:${port}\\n`)\n  });\n}\n"})}),"\n",(0,r.jsxs)(n.blockquote,{children:["\n",(0,r.jsxs)(n.p,{children:["\u261d\ufe0f For simplicity we defined whole configuration in one file. Normally once configuration grows you should\nmove each resource configuration to separate file and organize them to folder and import them in ",(0,r.jsx)(n.code,{children:"index.ts"}),"."]}),"\n"]}),"\n",(0,r.jsx)(n.p,{children:"Now you can run your app:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"npm start\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Open ",(0,r.jsx)(n.a,{href:"http://localhost:3500",children:"http://localhost:3500"})," in your browser and login with credentials ",(0,r.jsx)(n.code,{children:"adminforth"})," / ",(0,r.jsx)(n.code,{children:"adminforth"}),"."]}),"\n",(0,r.jsx)(n.p,{children:(0,r.jsx)(n.img,{alt:"alt text",src:t(8332).A+"",width:"2428",height:"1932"})}),"\n",(0,r.jsx)(n.h2,{id:"initializing-custom-directory",children:"Initializing custom directory"}),"\n",(0,r.jsxs)(n.p,{children:["If you are not using CLI, you can create ",(0,r.jsx)(n.code,{children:"custom"})," directory and initialize it with ",(0,r.jsx)(n.code,{children:"npm"}),":"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"cd ./custom\nnpm init -y\n"})}),"\n",(0,r.jsxs)(n.p,{children:["We will use this directory for all custom components. If you want to call your dir with other name then ",(0,r.jsx)(n.code,{children:"custom"}),", just set ",(0,r.jsx)(n.a,{href:"/docs/api/Back/interfaces/AdminForthConfigCustomization/#customcomponentsdir",children:"customComponentsDir option"})]}),"\n",(0,r.jsxs)(n.p,{children:["Also, for better development experience we recommend to create file ",(0,r.jsx)(n.code,{children:"custom/tsconfig.json"})," with the following content:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-json",children:'{\n  "compilerOptions": {\n    "baseUrl": ".",\n    "paths": {\n      "@/*": [\n        "../node_modules/adminforth/dist/spa/src/*"\n      ],\n      "*": [\n        "../node_modules/adminforth/dist/spa/node_modules/*"\n      ],\n      "@@/*": [\n        "."\n      ]\n    }\n  }\n}\n'})}),"\n",(0,r.jsx)(n.h2,{id:"possible-configuration-options",children:"Possible configuration options"}),"\n",(0,r.jsxs)(n.p,{children:["Check ",(0,r.jsx)(n.a,{href:"/docs/api/Back/interfaces/AdminForthConfig",children:"AdminForthConfig"})," for all possible options."]})]})}function h(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(c,{...e})}):c(e)}},8332:(e,n,t)=>{t.d(n,{A:()=>i});const i=t.p+"assets/images/localhost_3500_login-22b59511349c51948267c9a4080e4d87.png"},8453:(e,n,t)=>{t.d(n,{R:()=>o,x:()=>a});var i=t(6540);const r={},s=i.createContext(r);function o(e){const n=i.useContext(s);return i.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:o(e.components),i.createElement(s.Provider,{value:n},e.children)}}}]);