intellij-idea.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic SYSTEM "https://resources.jetbrains.com/stardust/html-entities.dtd">

<topic xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/stardust/topic.v2.xsd"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       title="Creating a new Ktor project"
       id="intellij-idea">

    <microformat>
        <p>
            <control>Final project</control>: <a href="https://github.com/ktorio/ktor-get-started-sample">ktor-get-started-sample</a>
        </p>
    </microformat>

    <excerpt>This guide shows how to create, run, and test a simple Ktor application.</excerpt>

    <p>
        Ktor is an asynchronous framework for creating microservices, web applications, and more.
        You can create and configure a new Ktor project using a dedicated plugin for IntelliJ IDEA Ultimate, or using a web-based project generator.
        In this guide, we'll show you how to create, run, and test a simple Ktor application.
    </p>


    <chapter title="Prerequisites" id="prerequisites">
        <include src="lib.xml" include-id="plugin_prerequisites"/>
    </chapter>


    <chapter title="Create a new Ktor project" id="create_ktor_project">
        <p>
            This section describes project setup using the <a href="https://plugins.jetbrains.com/plugin/16008-ktor">Ktor plugin</a> for Intellij IDEA Ultimate.
            If you are using IntelliJ IDEA Community Edition, use the <a href="https://start.ktor.io/">Ktor Project Generator</a> instead.
        </p>
        <p>
            To create a new Ktor project,
            <a href="https://www.jetbrains.com/help/idea/run-for-the-first-time.html">open IntelliJ IDEA</a>, and follow
            the steps below:
        </p>
        <procedure>
            <step>
                <include src="lib.xml" include-id="new_project_idea"/>
            </step>
            <step>
                <p>
                    In the <control>New Project</control> wizard, choose <control>Ktor</control> from the list on the left.
                </p>
            </step>
            <step>
                <p>
                    On the right pane, you can specify the following settings:
                </p>
                <img src="ktor_idea_new_project_settings.png" alt="Ktor Project Settings" width="706"/>
                <list>
                    <li>
                        <p>
                            <control>Name</control>:
                            Specify a project name.
                        </p>
                    </li>
                    <li>
                        <p>
                            <control>Location</control>:
                            Specify a directory for your project.
                        </p>
                    </li>
                    <li>
                        <p>
                            <control>Build System</control>:
                            Choose the desired <a href="server-dependencies.xml">build system</a>.
                            This can be <emphasis>Gradle</emphasis> with Kotlin or Groovy DSL, or <emphasis>Maven</emphasis>.
                        </p>
                    </li>
                    <li>
                        <p>
                            <control>Website</control>:
                            Specify a domain used to generate a package name.
                        </p>
                    </li>
                    <li>
                        <p>
                            <control>Artifact</control>:
                            This field shows a generated artifact name.
                        </p>
                    </li>
                    <li>
                        <p>
                            <control>Ktor version</control>:
                            Choose the required Ktor version.
                        </p>
                    </li>
                    <li>
                        <p>
                            <control>Engine</control>:
                            Select an <a href="Engines.md">engine</a> used to run a server.
                        </p>
                    </li>
                    <li>
                        <p>
                            <control>Configuration in</control>:
                            Choose whether to specify server parameters <a href="create_server.xml">in code or in a HOCON file</a>.
                        </p>
                    </li>
                    <li>
                        <p>
                            <control>Add sample code</control>:
                            Leave this option enabled to add sample code for plugins added on the next page.
                        </p>
                    </li>
                </list>
                <p>
                    In this tutorial, we leave the default values for these settings.
                    Click <control>Next</control> to go to the next page.
                </p>
            </step>
            <step>
                <p>
                    On the next page, you can choose a set of <a href="Plugins.md">plugins</a> -
                    building blocks that provide common functionality of a Ktor application, for example,
                    authentication, serialization and content encoding, compression, cookie support, and so on.
                </p>
                <img src="ktor_idea_new_project_plugins_list.png" alt="Ktor plugins" width="706"/>
                <p>
                    For now, let's install only the <a href="Routing_in_Ktor.md">Routing</a> plugin to
                    handle incoming requests.
                    Start typing <emphasis>routing</emphasis> in the top left search box,
                    find <control>Routing</control> in the list, and click <control>Add</control>.
                </p>
                <img src="ktor_idea_new_project_plugins.png" alt="Add the Routing plugin" width="706" border-effect="rounded" animated="true"/>
                <p>
                    Click <control>Create</control> and wait until IntelliJ IDEA generates a project and
                    installs the dependencies.
                </p>
            </step>
        </procedure>
        <p>
            Now we are ready to <a anchor="run_app">run</a> the created application.
        </p>
    </chapter>

    <chapter title="Run a Ktor application" id="run_app">
        <p>
            To run the <a anchor="create_ktor_project">created</a> Ktor application, follow the steps below:
        </p>
        <procedure>
            <step>
                <p>
                    Invoke the <a href="https://www.jetbrains.com/help/idea/project-tool-window.html">Project view</a>
                    and open the <path>Application.kt</path> file placed by the following path:
                </p>
                <path>src/main/kotlin/com/example/Application.kt</path>
                <img src="ktor_idea_new_project_view.png" alt="Project view" width="324"/>
            </step>
            <step>
                <p>
                    The <path>Application.kt</path> file has the following code added automatically:
                </p>
                <code style="block" lang="kotlin" initial-collapse-state="expanded" collapsed-title="fun main" src="https://raw.githubusercontent.com/ktorio/ktor-get-started/main/src/main/kotlin/com/example/Application.kt"/>

                <p>
                    The main parts of this code are:
                </p>
                <list>
                    <li>
                        <p>
                            The <a href="create_server.xml" anchor="embedded-server">embeddedServer</a> function is used to configure server parameters in code and run an application.
                        </p>
                    </li>
                    <li>
                        <p>
                            <code>configureRouting</code> is an extension function that defines <a href="Routing_in_Ktor.md">routing</a>. This function is declared in a separate <code>plugins</code> package (the <path>Routing.kt</path> file).
                        </p>
                        <code style="block" lang="kotlin" initial-collapse-state="expanded" collapsed-title="fun Application.configureRouting" src="https://raw.githubusercontent.com/ktorio/ktor-get-started/main/src/main/kotlin/com/example/plugins/Routing.kt"/>
                        <p>
                            The <code>get</code> function within the <code>routing</code> block receives GET requests made to the <path>/</path> path and responds with a plain text response.
                        </p>
                    </li>
                </list>
            </step>
            <step>
                <p>
                    To run the application, click the gutter icon next to the <code>main</code> function
                    and choose <control>Run 'ApplicationKt'</control>.
                </p>
                <img src="ktor_idea_new_project_run_gutter.png" alt="Run a Ktor application" width="706"/>
            </step>
            <step>
                <p>
                    Wait until Intellij IDEA runs the application.
                    The Run tool window should show the following message:
                </p>
                <code style="block">
                    [main] INFO  ktor.application - Responding at http://0.0.0.0:8080
                </code>
                <img src="ktor_idea_new_project_run_tool_window.png" alt="Run tool window" width="706"/>
                <p>
                    This means that the server is ready to accept requests at the <path>http://0.0.0.0:8080</path> address.
                    You can click this link to open the application in a default browser:
                </p>
                <img src="ktor_idea_new_project_browser.png" alt="Ktor app in a browser" width="430"/>
            </step>
        </procedure>
    </chapter>


    <chapter title="Test a Ktor application" id="test_app">
        <p>
            Now let's test the <a anchor="create_ktor_project">created</a> application:
        </p>
        <procedure>
            <step>
                <p>
                    Open the <path>ApplicationTest.kt</path> file placed by the following path:
                    <path>src/test/kotlin/com/example/ApplicationTest.kt</path>.
                    In this file, the <control><a href="Testing.md">testApplication</a></control> function is used to make the GET request to <path>/</path>
                    and check a response status and content.
                </p>
            </step>
            <step>
                <p>
                    To run a test, click the gutter icon next to the <code>testRoot</code> function and choose <control>Run 'ApplicationTest.test'</control>.
                </p>
                <img src="ktor_idea_new_project_run_test_gutter.png" alt="Run a test" width="706"/>
            </step>
            <step>
                <p>
                    Wait until IntelliJ IDEA performs a test and displays results in the Run tool window.
                </p>
                <img src="ktor_idea_new_project_run_test_output.png" alt="Run test output" width="706"/>
            </step>
        </procedure>
    </chapter>

    <chapter title="Next steps" id="next-steps">
        <p>
            Create real-world Ktor applications with the help of tutorials:
        </p>
        <list>
            <li>
                <p>
                    <a href="creating_http_apis.md"/>
                </p>
            </li>
            <li>
                <p>
                    <a href="creating_interactive_website.md"/>
                </p>
            </li>
            <li>
                <p>
                    <a href="creating_web_socket_chat.md"/>
                </p>
            </li>
        </list>
    </chapter>
</topic>