Skip to main content

Create Application

This guide provides an overview of the initial setup, covering the frontend, database, and API service. We will create a new full-stack application quickly and easily.

Introduction​

Although the platform is multilingual and supports several programming languages, we will focus exclusively on using JavaScript in this tutorial. As a result, we will create a practical application consisting of a form displayed in a modal (pop-up) window with the functionality to export data to PDF.

Prerequisites​

Before starting, make sure you have:

  • The Netuno platform pre-installed on your machine. If you have any questions at this stage, consult the guide Platform Installation.

  • Access to the terminal or command prompt of the development environment.

Creating a New Application​

Follow the instructions below to initialize your new application:

Open the terminal and navigate to the root folder where Netuno was installed.

Execute the application creation command:

./netuno app

Creating with Parameters​

It is possible to define the application name directly when executing the command, for example:

./netuno app name=my_application
Best Naming Practices

When defining your application name, avoid using spaces, accents, or special characters. Prefer the use of lowercase letters separated by hyphens or underscores (example: app-sales or hr_management) to maintain compatibility with URLs and system folders.

Initial Setting​

The command-line wizard will ask some questions to configure your project. Please provide:

  • Application Name: The identifier of your project.
  • Database Type: The database management system that will be used.
  • Language: The default language of your application's interface.
Tips and Best Practices

Database Recommendation for Beginners

During the step-by-step process, when prompted for the database type, we recommend choosing the H2 Database option.

H2 Database is an embedded database that comes integrated into the Netuno server. The great advantage is that it does not require the installation or configuration of external servers (such as PostgreSQL or MySQL), making initial development and testing much more practical and faster.

Command to Start the Server​

After creating your new application, start the Netuno platform server. This will make your project accessible in the browser and ready for continuous development.

Execute the command below in your terminal and wait for initialization.

./netuno server app=my_application

By passing the parameter app=my_application, the server understands that this will be the default application to be executed in this instance. With the server running, you can start editing your project.

All files and source code of your application are stored and organized within the folder 📂 apps/myapp.

Access Credentials (Backoffice)

When accessing the Backoffice administration interface of your application for the first time, the system will request authentication. For local development environments, use the following default credentials:

Username: dev

Password: dev

We recommend changing these credentials when moving your application to a production environment.

Code Editor​

To ensure the best development experience, we suggest using modern, lightweight code editors with a good ecosystem of extensions.

If you don't already have a favorite editor, we recommend the following free and widely used options in the community:

Note: If you prefer more robust tools and don't mind investing in licenses, JetBrains' WebStorm is an excellent premium option.

Open the application folder in your editor:

  • 📂 apps/my_application

All application files are stored and organized within this folder. All development, route creation, database logic, and visual interfaces will take place within this folder.

Understanding the Architecture

To know exactly where to create each type of file and how Netuno organizes the back-end and front-end, we recommend reading the detailed documentation on the application folder structure:

See the guide: Application Folders

Summary of Steps​

With the initial knowledge of Netuno consolidated, we will apply these concepts in practice, creating a complete functionality from start to finish.

The practical objective is to add two new interactive components to the interface:

  • A button responsible for loading and displaying the customer form within a floating window (Modal).
  • A button dedicated to generating and exporting the list of registered customers to a PDF file.

To achieve this result with organization and clarity, we have divided the development into a logical sequence of steps. We will follow this roadmap:

  • Interface Mapping: Analyze the application's folder structure to locate where the main HTML of the dashboard is defined.

  • Integration with React: Configure and add the base of the two new buttons using the React framework on the frontend.

  • Modal Logic: Build and program the button's behavior to correctly open the customer form.

  • Export Interface: Build and position the button that will trigger the download of the PDF file in the interface.

  • Service Development (API): Program the backend, creating the service that will read the data and dynamically generate the PDF file containing the list of clients.

Let's get started!

Dashboard Template​

Navigate to the server/templates folder and open the file responsible for providing the HTML for the dashboard screen.

server/templates/dashboard.html

While exploring the code in the dashboard.html file, scroll to the bottom of the page. You will find an isolated <div> element. This is exactly where the Netuno platform "injects" and starts the entire interactive interface built in React.

server/templates/dashboard.html
...
<div id="app-dashboard"></div>

Although the HTML skeleton is in the server/templates folder, the actual interface development and visual logic do not happen there.

To change the dashboard's behavior or add new components with React, you must access the folder dedicated to frontend development.

It is in this 📂 ui/ folder that you will find the dashboard components and can develop the new visual functionalities of your application.

Create Form​

In this step, we will create the database structure needed for this tutorial: a form called Client containing a text field called Name.

  • In the Backoffice, access the development area by clicking the Build button (upper right corner).
  • In the side menu, navigate to Management > Forms and create the new form with the Title: Client.
  • Click Save.

The table name will be automatically filled with client (keep it in lowercase, as recommended for databases).

Consult the Guide

If you have questions about the advanced settings of this screen, consult the complete documentation at Forms.

Create Field​

With the form created, it will appear in the left sidebar menu under the Fields category.

  • Click on Client to add a new column:
  • Enter the text "Name" in the Field Title.
  • Select the data type as "text" in the Type field.
  • Check the Allow Filtering (to enable searching) and Show in Results (to appear in the table) options.
  • Click Save.
Consult the Guide

To understand all available data types and their properties, access the detailed documentation at Fields.

Insert Test Data​

In order to test PDF export in the next steps, we need real data in the system.

  • Click the View button (upper right corner) to return to the application's back office.
  • Access the newly created Client menu on the side.
  • Use the + Add button to register some test clients in the system.
  • Click Save.

Database Query​

Netuno offers an integrated tool that allows you to execute SQL commands directly in your application's database. This is essential for performing quick queries, validating information, or manipulating system data efficiently.

To access the query interface and execute your commands, follow the steps below:

  • In the main interface, access the development area by clicking the Build button.
  • In the side navigation menu, locate the Management section.
  • Click the Query option to open the database console.
  • In the text editor that appears on the screen, type the SQL command you wish to execute.
  • Confirm the execution of the command.

Execute the command below to query registered clients:

SELECT * FROM client

When you finish the queries and wish to return to the system's user interface (back office), simply click the View button.

Add Buttons with React​

In this step, we will configure the main dashboard file to display two new buttons.

In interface architecture, we use the concept of Containers to define broad areas of the system, encompassing larger functionalities and grouping multiple smaller components.

  • In your code editor, navigate to the containers folder in 📂 ui/src/containers.

  • Locate and open the main dashboard file: 📂 DashboardContainer/index.jsx.

  • Insert the import and rendering code for the components as shown in the example below.

ui/src/containers/DashboardContainer/index.jsx
import { Space } from 'antd';

import CustomerModalButton from '../../components/CustomerModalButton';
import PDFButton from '../../components/PDFButton';

import "./index.less";

function DashboardContainer() {
    return (
        <div className="my-dashboard">
            <Space>
                <CustomerModalButton />
                <PDFButton />
            </Space>
        </div>
    );
}

export default DashboardContainer;

Note that these button files do not yet physically exist in your project. Since they are smaller, reusable components, we will create them within the dedicated components folder.

Architecture Organization

Always maintain a separation between Containers (widely sized areas, such as entire pages or dashboards) and Components (isolated interface elements, such as buttons and modals). This makes your code in Netuno much cleaner, easier to maintain, and more scalable.

Button for Form​

Access the ui/src/components/ folder and create a new folder called CustomerModalButton.

Inside the CustomerModalButton folder, create the main component file named index.jsx.

📂 ui/src/components/CustomerModalButton/index.jsx

Open the file and enter the code below:

ui/src/components/CustomerModalButton/index.jsx
import { Button } from 'antd';

function CustomerModalButton() {
    const onClick = () => {
        netuno.modal.create({
            name: 'customer',
            callback: function (modal) {
                let form = modal.find('[netuno-form]');

                form.on('netuno:new', () => {
                    console.log('Creating a new Customer.');
                });

                form.on('netuno:save', () => {
                    netuno.modal.hide(modal)
                    console.log('Saved a Customer.');
                });

                form.on('netuno:delete', () => {
                    netuno.modal.hide(modal)
                    console.log('Removed a Customer.');
                });

                form.on('netuno:back', () => {
                    console.log('Clicked back.');
                });

                netuno.loadForm(form);
                netuno.modal.show(modal);
            }
        });
    };
    return (
        <div>
            <Button type="primary" onClick={ onClick }>
                Open Customer Form
            </Button>
        </div>
    );
}

export default CustomerModalButton;

Understanding the Code​

The magic of this component happens within the onClick function, which uses Netuno's global interface tools:

  • netuno.modal.create(): This method is responsible for instantiating the modal window on the screen and linking the desired form to it (in this case, the form called client).

  • Form Events (form.on): The callback block allows us to "listen" for user actions. We can trigger custom actions when the user creates a record (netuno:new), saves (netuno:save), deletes (netuno:delete), or clicks back (netuno:back).

  • netuno.modal.hide() / show(): Methods used to hide the modal after a successful action or display it as soon as the form is loaded.

Integration Completed

Now that the CustomerModalButton component has been successfully created, the import we previously performed in your DashboardContainer will now work without errors, and the button should now be rendered on your screen!

PDF Export Button​

In this step, we will create the second button for the Dashboard: the PDF Export Button.

The main function of this component in the interface is to act as a trigger; that is, when clicked, it will make a request to a backend service, responsible for processing the system data and generating the PDF file containing the list of registered clients.

  • Access the ui/src/components/ folder and create a new folder called PDFButton.

  • Create a file called index.jsx inside the folder.

ui/src/components/PDFButton/index.jsx

Open the file and insert the code below:

ui/src/components/PDFButton/index.jsx
import { Button } from 'antd';

function PDFButton() {
    return (
        <div>
            <Button
                type="primary"
                href="/services/customer/pdf-export"
                target="blank">
                Generate PDF
            </Button>
        </div>
    );
}

export default PDFButton;

With the creation of the PDFButton component, both buttons declared in your DashboardContainer are ready.

Next Steps

The visual structure and components are complete. Compile the frontend to test the interface rendering.

The construction of the backend service that will actually generate the PDF will be addressed in the next step.

Compile Frontend​

Web browsers do not natively understand React code in .jsx or .tsx files and CSS pre-processors like .less. For your interface to function correctly, it needs to go through a compilation (build) process. This process translates, packages, and optimizes all your code into final static files (standard JavaScript and CSS) that the browser can process with maximum efficiency.

Prerequisites​

Before starting the compilation, make sure that:

  • You have the terminal or command prompt open in your development environment.

  • The Bun package manager is correctly installed on your system.

Compilation Examples​

Netuno provides different commands depending on the stage of your development. From the Netuno root folder, navigate to the ui folder of your application.

Execute the commands within your application's interface folder: 📂 apps/myapp/ui

Production Compilation​

Performs a complete and optimized compilation of the files. It is the ideal command when you finish developing a screen or component and want to generate lightweight final files with better performance.

bun run build

Development Compilation​

The watch command performs a quick compilation and monitors the folder. Whenever you save a file in your editor, the terminal automatically executes the compilation.

bun run watch

Regardless of the command used, build or watch, the changes do not appear instantly on the user's screen. Refresh the backoffice page in your browser to load the newly generated files.

Error Monitoring and Debugging

During development, errors can occur at two different stages. Learn where to look for them:

  • Compilation Errors: Syntax errors in React code or undeclared variables will be displayed directly in your terminal, where the bun command is running.

  • Run-Time Errors: Errors that occur during application use will be displayed in the browser console. Always remember to inspect the page to check for any alerts or errors.

Integrated Compilation​

The integrated compilation feature allows you to automatically execute terminal commands along with server startup. This optimizes workflow by consolidating all logs and monitoring into a single central terminal.

To enable integrated compilation, you need to modify your application's development settings:

  • Access your application's root folder.

  • Open the development configuration file: _development.json.

  • Locate the code block related to "commands".

  • Change the value of the "enabled" property from false to true.

  • Save the file.

Your _development.json file should have a structure similar to this:

config/_development.json
  ...
  "commands": [{
    "command": "bun run watch",
    "enabled": true,
    "install": "bun install",
    "path": "ui"
  }],
  ...

To allow Netuno to read the updated file and apply the new configuration, it is necessary to restart the server:

  • Go to the terminal where the Netuno server is running.

  • Terminate the process by pressing CTRL + C simultaneously.

  • Start the server again, specifying the name of your application:

./netuno server app=myapp
Single Terminal

After restarting the server, observe the logs in the terminal. You will notice that Netuno is now automatically executing the frontend compilation commands bun run watch in the background. From now on, everything works integrated in the same window.

API Service to Generate PDF​

In the previous step, we configured the Export PDF button on the frontend with the "href" attribute pointing to the address services/client/export-pdf. However, if you click it now, nothing will happen. This is because the API service responsible for generating the file does not yet exist.

All API development takes place within the 📂 server folder. In this section, we will create the script that retrieves records from the database and builds the PDF document visually.

Prerequisites​

  • Have created the PDFButton component on the frontend pointing to the correct URL.
  • Have the Netuno server running.

Netuno automatically routes your API URLs based on the folder structure within server/services/. To create the service, follow these steps:

  • Navigate to the backend services folder: server/services/. Create a folder called client.

  • Inside this folder, create a file called exporta-pdf.js.

Netuno is multilingual. We will use JavaScript in this example; use the extension corresponding to your preferred language.

Open the file and enter the code below to generate your PDF structure:

  • server/services/client/pdf-export.js
server/services/client/pdf-export.js
_header.contentType("pdf")

const pdfDocument = _pdf.newDocument(_pdf.pageSize("A5"))

pdfDocument.add(
    _pdf.paragraph("Customers List:")
        .setFontSize(16)
        .setFontColor(_pdf.color("#1abc9c"))
)

const dbCustomers = _db.form("customer").all()

for (const dbCustomer of dbCustomers) {
    pdfDocument.add(
        _pdf.paragraph(dbCustomer.getString("nome"))
            .setFontSize(12)
            .setFontColor(_pdf.color("#748dae"))
    )
}

pdfDocument.close()

Understanding the Code​

  • _header.contentType("pdf"): Tells the browser that the response to this request is not a regular text or JSON file, but a PDF file.

  • _pdf: This is Netuno's native resource for manipulating PDFs. With it, we define the page size (A5), create paragraphs, adjust font sizes (setFontSize) and colors (setFontColor).

  • _db.form("cliente").all(): Queries the database and returns all records saved in the "cliente" form. The loop (for) iterates through each of these clients and extracts the information from the "nome" field to print in the document.

  • pdfDocument.close(): Finalizes the document construction and sends it as a response.

Validation and Testing​

It's not necessary to click the dashboard button every time you want to test your service. Since it's a simple request (GET), you can validate the execution by accessing the API URL directly through your browser.

For this example, access the following address: http://localhost:9000/services/cliente/exporta-pdf

If the PDF file is generated and displayed on the screen containing the client list, the service is working perfectly! Consequently, the Export PDF button on your Dashboard will start working automatically.

Backend Error Tracking

If the page is blank or returns an error message when accessing the URL, immediately check the terminal where the Netuno server is running. Unlike the frontend, whose errors appear in the browser console, any execution failure in the scripts in the server folder will be displayed in detail in the backend server terminal.

Conclusion​

In this tutorial, you went through a practical journey of full-stack development using Netuno.

The main objective was to demonstrate how the platform integrates the construction of visual interfaces with server robustness, always focusing on high productivity.

Recapping the completed steps:

  • Frontend Development: customized the dashboard in React, creating interface components and interactive buttons in a modular way.

  • Data Management and Structure: saw how quick it is to create forms and fields in the panel to register and manipulate information without needing to write complex persistence routines.

  • Direct Queries: used the Query feature to execute SQL commands quickly, testing the database.

  • Backend API Creation: developed a service for PDF generation and observed one of Netuno's great advantages: hot-reload. You don't need to restart the server with every change in the backend code, which greatly speeds up programming.

  • Optimized Environment: Configures integrated compilation, centralizing frontend and backend processes in a single terminal to maintain focus and avoid distractions.

The platform was designed from the ground up to optimize and accelerate software development. Now that you understand the basic integration flow between low-code and custom code, you are ready to build much more complex and scalable applications.

Continue exploring the next sections of the documentation to master new features.

Development becomes much easier when you are part of an active community. Access the social media links in the footer of this page.