@sv-cd/sv v0.0.9

• Fast mode development and build for production!
• Make in typescript! :D
• Use ejs templates(for default...) for pages and components!

Table of Contents

• How get?
• Sv-cli
  • ¿How use sv-cli?
  • ¿How use sv-cli in mode dev?
  • ¿How use plugins in sv-cli?
• Concepts basics
  • Structure your directorys
  • Routes
• Config Files
  • File config.data.js
  • File create.pages.js
  • File sv.config.js
• How to build my project for production?
• How can I test my project in production?
• API
  • Helpers
    • Parameters
  • setFilesJson
    • Parameters
    • Examples
  • setFilesJsonPromise
    • Parameters
    • Examples
  • getJson
    • Parameters
    • Examples
  • getJsonPromise
    • Parameters
    • Examples
  • isPromise
    • Examples
  • setFilesMarkdown
    • Parameters
    • Examples
  • setFilesMarkdownPromise
    • Parameters
    • Examples
  • getMarkdown
    • Parameters
    • Examples
  • getMarkdownPromise
    • Parameters
    • Examples
• Experimental

How get?

Run:

  npm install @sv-cd/sv -D

Sv-cli

Use serVer cli.

¿How use sv-cli?

$ sv help
Usage: sv [options] [command]

Options:
  -v, --version    sv version
  -d, --discord    This command is for discord users, active 'Rich presence' (default: false)
  -h, --help       display help for command

Commands:
  dev [options]    Starting your proyect in mode development
  build [options]  Starting build of your project for production
  start [options]  Start your application for production
  help [command]   display help for command

¿How use sv-cli in mode dev?

In dev(development) mode, it comes by default, these are the commands in this mode.

  $ sv dev -h
  Usage: sv dev [options]

  Starting your proyect in mode development

  Options:
    -off, --offline                Active offline version (default: false)
    --open                         Open default browser (default: false)
    -p,--port <port_number>        This is the port where you will work in development mode (default:     "5000")
    --root <root_proyect>          Is a root of your proyect (default: "src")
    --plugins <plugins>            Plugins of server
    --d-styles <d-styles>          Style's directory (default: "styles")
    --d-scripts <d-js>             Javascript's directory (default: "js")
    --d-components <d-components>  Components's directory (default: "components")
    --d-assets <d-assets>          Assets's directory (default: "assets")
    -h, --help                     display help for command

¿How use plugins in sv-cli?

Use plugins create for server.

  $ sv --plugins @sv-cd/plugin-init:withoutComments=false,exclude=css-js --otherPlugin:hisOptions--...

To make it easier to understand, we recommend using sv.config.js, go to svConfig.

Concepts basics

There is a concepts basics for use serVer

Structure your directorys

serVer use a structure for your pages, styles, javascripts and assets.

Use a structure similar to this.

You can save time by installing the @sv-cd/plugin-init plugin which creates all the directories according to your configuration.

  📦src
  ┣ 📂assets
  ┃ ┣ 📜codedoctors.png
  ┃ ┗ 📜html.png
  ┣ 📂components
  ┃ ┗ 📜header.ejs
  ┣ 📂styles
  ┃ ┣ 📜styles.css
  ┣ 📂[Directory of your templates]
  ┃ ┗ 📜post.ejs
  ┣ 📂js
  ┃ ┣ 📜index.js
  ┣ 📂pages
  ┃ ┣ 📂dashboard
  ┃ ┃ ┗ 📜settings.ejs
  ┃ ┣ 📜index.ejs

Routes

SerVer has a file-system based router built on the concept of pages.

When added a file .ejs in the carpet pages, automatically available as a route.

The router will automatically routes files named index to the root of the directory pages.

• pages/index.ejs → /
• pages/blog/index.ejs → /blog

These routes are generated when you create a subfolder within a folder, this in the directory pages.

• pages/user/profile.ejs--> /user/profile
• pages/posts/html.ejs--> /posts/html

Config Files

File config.data.js

This is a file where you can add variables to your ejs files.

Create a file named config.data.js

Accept module/exports Ecmascript 6+ and CommonJS

Squemas:

  exports.[page] = {
    [variable: (string | number)]: // Function, string, object, any
  }

  export const [page] = {
    [variable: (string | number)]: // Function, string, object, any
  }

Examples

// This variable is available on the index page
export const index = {
  title: "First Proyect with serVer",
};
// With commonJs
exports.index = {
  title: "First Proyect with serVer",
};

File create.pages.js

This is a file where you can create pages programmatically

Create a file named create.pages.js

Accept module/exports Ecmascript 6+ and CommonJS

Examples

// With helpers and module/exports Ecmascript 6+
import { Helpers } from "@sv-cd/sv";

export default function createPage({ action, listenTemplate }) {
  // This is helpers of sv
  const { getJson } = new Helpers().setFilesJson("./src/posts", "id");
  // This for the server watch this directory
  listenTemplate("./src/templates");
  // This is implemantion
  getJson().forEach(({ data, name }) => {
    action({
      data,
      path: name,
      template: "./src/templates/post.ejs",
    });
  });
}

// With Custom data and commonJS
// If you want use helpers
// const { Helpers } = require('@sv-cd/sv');

modules.exports = function createPage({ action, listenTemplate }) {
  const pages = [
    {
      name: "First-page",
      data: {
        mode: "development",
        title: "My first page programmatically",
      },
    },
  ];
  // This for the server watch this directory
  listenTemplate("./src/templates");
  // This is implemantion
  pages.forEach(({ data, name }) => {
    action({
      data,
      path: name,
      template: "./src/templates/post.ejs",
    });
  });
};

File sv.config.js

Used when your options are too many.

For use, you need create a file named sv.config.js

Examples:

// sv.config.js
module.exports = {
  root: "./src",
  devOptions: {
    globalVars: {
      mode: "development",
    },
    port: 5000,
    open: false,
  },
  plugins: [],
  buildOptions: {
    dist: "public",
  },
};

Options

Options.root

@type: string
Root is a relative path where the main folder of your project is, in case it is the root put
"."
@default: "src"

Options.plugins

@type: Array<{
  name: string,
  options: object,
}>`
Plugins of serVer
@default: []

You can some plugins in https://www.npmjs.com/org/sv-cd.

Options.globalVars

@type object
It is an object with variables that will be available on all your pages
@default: {}

Options.dirs

@type object
It is an object with dirs(These paths must be relative to root)
@default: {
  styles: 'styles',
  scripts: 'js',
  components: 'components',
  assets: 'assets',
}

Options.devOptions.styles

@type string
This path is where your styles are (only `css` by default)
@default 'styles'

Options.devOptions.scripts

@type string
This path is where your scripts are (only `js` by default)
@default 'scripts'

Options.devOptions.components

@type string
This path is where your components ejs(default)
@default 'components'

Options.devOptions.assets

@type string
This path is where your assets, anything files(images, json for PWA, etc)
@default 'assets'

Options.devOptions

@type: object
Is a object with your config dev of server.
@default: {
  port: 5000,
  open: false,
}

Options.devOptions.port

@type number
It is a port where will open server!
@default: 5000

#### **_Options.devOptions.open_**

@type number
If this option in true, will open your browser.
@default: false

Options.devOptions.open

@type number
If this option in true, will open your browser.
@default: false

Options.buildOptions

@type: object
Is a object with your config build of server.
@default: {
  dist: string
}

Options.buildOptions.dist

@type: string
It is a relative path to where your production directory will be.
@default "public"

How to build my project for production?

Is simple, only run this command once.

  sv build

For look options:

$ sv build -h
  Usage: sv build [options]

  Starting build of your project for production

  Options:
    --root <root_proyect>          Is a root of your proyect (default: "src")
    --dist <dist_proyect>          Is a place where will bundle of your project (default: "public")
    --plugins <plugins>            Plugins of server
    --d-styles <d-styles>          Style's directory (default: "styles")
    --d-scripts <d-js>             Javascript's directory (default: "js")
    --d-components <d-components>  Components's directory (default: "components")
    --d-assets <d-assets>          Assets's directory (default: "assets")
    -h, --help                     display help for command

After of run this command, creates a carpet of your application's bundle.

For default is public but you can change in buildConfig.

How can I test my project in production?

We can test the project in production, with this simple command.

  sv start

You can change the port with the --port flag.

API

Helpers

This is a class where you can initialize the helpers of serVer, like json, markdown(experimental)

Parameters

• param Object is a configuration object
  • param.promise boolean this attribute converte all methods to promise (optional, default false)
  • param.test boolean this attribute delete watch of your files (optional, default false)

setFilesJson

This method is for set path of your files json

Parameters

• params (string | {dir: string, id: string}) This is the relative path where are your files json (optional, default ./src/jsons)
• id string? This id save a instance json

Examples

// returns a array of your data
// In create.pages.js
const functionCreatePage = () => {
const jsons = new Helpers().setFilesJson('./src/jsons', 'id').getJson();
// or
const jsons = new Helpers().setFilesJson({
 dir: './src/jsons',
 id: 'id',
}).getJson();
}
export default functionCreatePage;

Returns {getJson} where is getJson, this method is where you get your data

setFilesJsonPromise

This method is for set path of your files json

Parameters

• params (string | {dir: string}) This is the relative path where are your files json (optional, default ./src/jsons)

Examples

// returns a array of your data
// In create.pages.js
const functionCreatePage = async () => {
const { getJsonPromise } = await new Helpers().setFilesJson('./src/jsons', 'id');
// or
const { getJsonPromise } = await  new Helpers().setFilesJson({
 dir: './src/jsons',
 id: 'id',
});
}
export default functionCreatePage;

Returns Promise<{getJsonPromise}> is a promise that return in then the objet with the method getJsonPromise(this is for get your data in a promise)

getJson

This method return all data of your json files

Parameters

• id string is a id of your instance files json

Examples

// In create.pages.js
const functionCreatePage = () => {
new Helpers().setFilesJson('./src/jsons', 'id');
// returns all data
 const dataJson = new Helpers().getJson('id');
};
export default functionCreatePage;

getJsonPromise

This method return all data of your json files wrapped in a promise

Parameters

• id string is a id of your instance files json

Examples

// In create.pages.js
const functionCreatePage = async () => {
await new Helpers().setFilesJsonPromise('./src/jsons', 'id');
// returns all data
 const dataJson = await new Helpers().getJsonPromise('id');
};
export default functionCreatePage;

Returns Promise<{id: string, dir: string, data: Array<{name: String, pathRelative: String, data: Object}>}> is a promise that return all your data of json files

isPromise

This method return if your methods are promises

Examples

const { isPromise } = new Helpers();
console.log(isPromise());
// Output: false

Returns boolean A boolean if your methods Helpers are promises

setFilesMarkdown

This method return all data of your json files

Parameters

• params (string | {dir: string, id: string}) This is the relative path where are your files markdown (optional, default ./src/md)
• id string? This id save a instance markdown

Examples

// returns a array of your data
// In create.pages.js
const functionCreatePage = () => {
const md = new Helpers().setFilesMarkdown('./src/md', 'id').getMarkdown();
// or
const md = new Helpers().setFilesMarkdown({
 dir: './src/md',
 id: 'id',
}).getMarkdown();
}
export default functionCreatePage;

Returns {getMarkdown} where is getMarkdown, this method is where you get your data(in parser html)

setFilesMarkdownPromise

This method return all data of your json files

Parameters

• params (string | {dir: string, id: string}) This is the relative path where are your files markdown (optional, default ./src/md)
• id string? This id save a instance markdown

Examples

// returns a array of your data
// In create.pages.js
const functionCreatePage = async () => {
 const { getMarkdownPromise } = await new Helpers().setFilesMarkdownPromise('./src/md', 'id');
 // or
 const { getMarkdownPromise } = await new Helpers().setFilesMarkdownPromise({
   dir: './src/md',
   id: 'id',
 });
}
export default functionCreatePage;

Returns {getMarkdownPromise} where is getMarkdown, this method is where you get your data(in parser html)

getMarkdown

This method return all data of your markdown files

Parameters

• id string is a id of your instance files markdown

Examples

// In create.pages.js
const functionCreatePage = () => {
new Helpers().setFilesMarkdown('./src/markdown', 'id');
// returns all data
 const dataMarkdown = new Helpers().getMarkdown('id');
};
export default functionCreatePage;

Returns {id: string, data: Array<string>, dir: string} are all your data and config of markdown files(parsed to html).

getMarkdownPromise

This method return all data of your markdown files

Parameters

• id string is a id of your instance files markdown

Examples

// In create.pages.js
const functionCreatePage = async () => {
await new Helpers().setFilesMarkdown('./src/markdown', 'id');
// returns all data
 const dataMarkdown = await new Helpers().getMarkdownPromise('id');
};
export default functionCreatePage;

Returns Promise<{id: string, data: Array<string>, dir: string}> are all your data and config of markdown files(parsed to html).

Experimental

In your pages, in dev mode, using Turbo drive to be able to make it SPA, we recommend reading the documentation of this amazing library to be able to solve some problems with this strategy that we take. We resume, it is experimental.